OCI Agent Shipyard

Build, ship, and run AI agents on OCI Enterprise AI Hosted Applications, with plain-language requests to Codex.

Install the skills once, then use them from the repository of any agent: Codex creates the agent, builds and publishes its image, deploys it, and verifies the release, asking for your approval before every change in OCI.

New here? Start with Getting started for macOS and Linux or Windows, from an empty workstation to your first agent; then use the Quickstart for new versions and rollback.

Why use it

• From an idea to an agent, specification first. Describe the agent in a few sentences: oci-agent-new drafts a specification (agent-spec.md) that starts from the business context (customer persona, use case, expected outcomes) and applies proven defaults. You review and edit it; only after your approval does it generate the agent code and the manifest, ready to build and deploy.
• Plain language. "Release version 0.2.0 of this agent" runs the whole chain: build, push, deploy, verify.
• Plan first, then approve. Every remote change is shown before it happens and runs only after your explicit approval.
• Versions and rollback in place. New versions and rollbacks reuse the same Hosted Application, so the endpoint never changes.
• One manifest per agent. agent.yaml describes build, publish, deploy, runtime variables, and functional checks; the version tag is always explicit.
• Bash and PowerShell. Every lifecycle script has twins with the same options and exit codes, for macOS, Linux, WSL2, and Windows.

From a prompt to a running agent

flowchart LR
    You(["You describe the agent"]) --> New["<b>oci-agent-new</b><br/>create the repository"]
    New --> Build["<b>oci-agent-build</b><br/>build and verify locally"]
    Build -- "your approval" --> Push["<b>oci-agent-push</b><br/>publish to OCIR"]
    Push -- "your approval" --> Deploy["<b>oci-agent-deploy</b><br/>plan, then deploy"]
    Deploy --> Verify["<b>oci-agent-verify-deployment</b><br/>check the release"]
    Verify --> Live(["Agent live on OCI"])
    Live -. "optional" .-> UI["<b>oci-agent-ui</b><br/>demo page for its users"]
    Live -. "when no longer needed" .-> Teardown["<b>oci-agent-teardown</b><br/>remove everything"]

Loading

Skill	What it does	Changes
oci-agent-new	Creates an agent repository from a prompt or a specification file: agent.yaml, Dockerfile, a FastAPI app, and functional checks.	Local files only.
oci-agent-build	Builds a linux/amd64 image and verifies it locally, read-only, with its functional checks.	Local Docker only.
oci-agent-push	Publishes the verified image to OCIR.	Creates a missing repository and pushes, each only with your approval.
oci-agent-deploy	Plans the release from the state in OCI, then deploys it and waits for the outcome.	Creates or updates OCI resources only with your approval.
oci-agent-verify-deployment	Checks the deployed release: OCI state, /health, /ready, and optional functional checks.	Read-only OCI calls and approved endpoint calls.
oci-agent-ui	Creates a local demo web page (Next.js) for the agent's users, in business language, from its specification.	Local files only; runs on your computer.
oci-agent-teardown	Removes an agent completely: Hosted Application and deployment, managed storage, OCIR repository with its images, and local images.	Deletes, only with your approval and the typed application name.

The skill catalog explains discovery, installation, and the Bash/PowerShell mapping; each SKILL.md is the authoritative instruction.

Talk to Codex

Open your agent's repository in Codex and ask:

You say	What happens
"Create a new OCI agent: POST /analyze receives a text and returns the number of words."	oci-agent-new asks for anything missing, shows the files it will create, then writes them.
"Release version 0.1.0 of this agent on OCI Hosted Applications."	Build, push, deploy, and verify, with an approval before each change in OCI.
"Release version 0.2.0 of this agent on OCI Hosted Applications."	The new version replaces the old one in the same application; the endpoint stays the same.
"Deploy version 0.1.0 of this agent again. Deploy only: do not build or push."	Rollback: the earlier version becomes active again.
"Verify the deployment of this agent, version 0.2.0, and also run its functional checks."	Read-only checks of OCI state, probes, and functional checks.
"Remove this agent and all its resources from OCI."	oci-agent-teardown shows what it would delete and what it keeps, then deletes only after your approval and the typed application name.
"Create a demo UI for this agent, for its users."	oci-agent-ui drafts the page's specification, then, after your approval, creates a local demo page with example requests.

You can also call a skill by name, for example $oci-agent-build ./agent.yaml tag: 0.4.0.

Release lifecycle

The deploy skill decides from the state in OCI what each release means:

stateDiagram-v2
    direction LR
    [*] --> Creating: First release
    Creating --> Active: creation completes
    Creating --> Failed: OCI reports FAILED
    Active --> Active: new version, or rollback to an earlier tag
    Failed --> Creating: you ask for a new deploy and approve the replacement

Loading

• Already released: deploying the active tag changes nothing.
• Waiting: the deploy waits for OCI and shows progress; if its timeout expires (exit 26), OCI is still working and running the deploy again resumes the wait.
• Failed deployment: the deploy reports the OCI error and stops. Only if you ask for a new deploy, and approve the plan, does it replace the failed deployment.
• Old versions stay in the application, up to 20, ready for rollback.

All cases and their exact names: release cases.

Setup

Follow the guide for your operating system, once per workstation: macOS and Linux (also Windows inside WSL2) or Windows (PowerShell 7). Each takes you, with commands to copy, from an empty workstation to your first agent on OCI:

1. the basic tools: Git, Anaconda, a container engine (Docker Desktop, Rancher Desktop, or on Windows Podman), and Codex;
2. this project, cloned in a stable folder: it is the tool home, keep it where it is;
3. the Python environment and its libraries;
4. the OCI CLI profile;
5. the tool's .env;
6. the skills;
7. the setup check;
8. the fixes for what fails;
9. a test release of the example agent;
10. your first agent;
11. optionally, a demo page for its users.

Your tenancy administrator prepares the compartment and the IAM policies once: see Setup for the administrator.

The agent manifest

Every agent has a versioned agent.yaml next to its code:

schema_version: 2
name: hello-world
build:
  context: .
  dockerfile: Dockerfile
publish:
  repository: agents/hello-world
deploy:
  application_name: hello-world
  profile: public-noauth        # or public-idcs: callers need a JWT token
runtime:
  env:
    - name: LOG_LEVEL
      value: INFO
    - name: GENAI_API_KEY
      from_env: GENAI_API_KEY   # from your shell, or from the tool's .env
verify:
  - method: POST
    path: /hello
    body: {name: Luigi}
    expect_status: 200

The version tag is never stored in the manifest: pass a new one for every release. Every field, with complete examples for both access modes, is in the agent manifest reference.

Security

Important

Nothing changes in OCI without your explicit approval. The skills show a plan first, and a request to deploy never authorizes a push on its own.

Warning

Never put a secret in agent.yaml, in a command argument, or in the chat. Agent secrets such as GENAI_API_KEY go only in your shell or in the tool's .env, which is never shared or committed. Never put an OCI auth token, OCI API private key, or registry login credential in .env: type the OCIR auth token only at the selected engine's docker login or podman login password prompt.

• For public-idcs, store only the non-secret domain URL, audience, and scope in the manifest. Put the client ID and secret in the tool's .env (or export them) for the verification, and in the agent's ui/.env.local for its demo UI; both files are ignored by Git. See Protecting an agent with JWT tokens.
• Agents that call OCI Generative AI can use Resource Principal instead of an API key: the Hosted Application authenticates as itself, with no secret to manage. It needs a Generative AI project and the runtime policies in IAM policies.
• A variable passed with from_env stays out of your repository and is shown as value=<hidden> in every report, but it is stored in the Hosted Application configuration in OCI.

Documentation

Read	To
Getting started for macOS and Linux or Windows	Prepare a workstation step by step and create your first agent.
Quickstart	Publish, update, and roll back an agent with plain-language requests.
Step-by-step guide	Understand each step, its inputs, and its outputs.
Agent manifest reference	Write agent.yaml.
IAM policies	Prepare the permissions for operators and Hosted Applications.
Logging in to OCIR	Build the registry username, generate the auth token, and log in.
Protecting an agent with JWT tokens	Create the identity-domain confidential application for the public-idcs profile, test a token, and fill in agent.yaml.
hello_world demo	Run the reference FastAPI/LangGraph agent.
Specifications	See design decisions, acceptance criteria, and verification records.

Project layout

Directory	Purpose
skills/	Codex skills for the lifecycle steps.
scripts/	Lifecycle automation, as Bash and PowerShell twins, and shared Python modules.
demos/	Runnable agent examples.
docs/	Operator guides and platform documentation.
notes/	Architectural and environment notes.
specs/	Specifications, acceptance criteria, and verification records.
tests/	Local unit tests and explicit integration-test support.

Contributing

Follow AGENTS.md: specify meaningful changes first in specs/, write documentation and comments in English, and record remote OCI verification in the relevant specification.

License

MIT.