Skip to main content

Getting Started

This guide gets you from zero to invoking your first agent through O2AGENT's Gateway, with a full trace of what happened.

Prerequisites​

  • A Docker-API-compatible container runtime (Docker Engine, Docker Desktop, Colima, OrbStack, Rancher Desktop, or Podman)

Install the CLI​

curl -fsSL https://o2agent.pages.dev/install.sh | sh

This downloads the right o2agentctl binary for your OS/architecture from GitHub Releases and installs it to /usr/local/bin — already on your PATH, nothing else to configure.

1. Start the platform​

docker run -d --name o2agent \
  -p 8000:8000 -p 8080:8080 \
  -v o2agent-data:/data \
  -e PLATFORM_ADMIN_EMAIL=you@example.com \
  -e PLATFORM_ADMIN_PASSWORD=<choose-a-password> \
  ghcr.io/o2stack/o2agent:latest

One container, everything included: O2ID, Postgres, the Registry, the Gateway, and the Runtime worker. PLATFORM_ADMIN_EMAIL and PLATFORM_ADMIN_PASSWORD are required — they become O2ID's admin account on first run; the container refuses to start without them.

note

This quickstart image is a fast way to try O2AGENT — it isn't the production deployment topology. For that (independently scaled services, an external Postgres, etc.), see the multi-service docker-compose.yaml instead — same platform, split into its real services.

2. Register o2agentctl (one-time per O2ID instance)​

o2agentctl bootstrap

This opens your browser — log in as the O2ID admin account you just created. o2agentctl registers itself with O2ID automatically; there's no separate tool to install or manual application to configure.

3. Log in and create your first agent​

o2agentctl login

o2agentctl agent create --name demo

o2agentctl agent version create --agent <agent-id> \
  --system-prompt "You are a helpful assistant." \
  --model-provider mock --model-name mock-1

o2agentctl agent deploy --agent <agent-id> --version <version-id>

4. Invoke it​

o2agentctl agent invoke --agent <agent-id> --input "hello there"

o2agentctl trace tail

Every command supports --output json for scripting and CI. Prefer an interactive view? Run o2agentctl tui for a full-screen agent list, invoke playground, and live trace tail.

Using a real model​

Swap the mock provider for a real one by creating a version with --model-provider openai-compatible --model-name gpt-4o-mini (or your provider's model name), and pass your key to the container: -e OPENAI_API_KEY=<your-key> on the docker run command from step 1 (add -e OPENAI_BASE_URL=... too if you're pointing at a self-hosted or alternative OpenAI-compatible endpoint).

Next steps​

  • Concepts — understand agents, versions, tools, and how identity works.
  • CLI Reference — the full command list.