Skip to main content

Use your own subscription

By default, Agenta runs agents with a model API key it resolves for each run. You can instead run agents with your own harness subscription: a Pi login, a Claude Code login, or a ChatGPT/Codex login.

A subscription authenticates the harness through a directory mounted into the runner container, so it works only with local runs. Agenta never uploads the login to a Daytona sandbox, and a Daytona run cannot use one.

This tutorial mounts your login into the runner container and runs an agent that uses it.

This is for a single trusted operator

One personal subscription serves one operator, not every user of a shared deployment. Every local run can read the files mounted into the runner container, including this login. Use this only on a deployment you run for yourself. See Sandbox isolation and security.

Before you start​

  • A running local OSS stack. See the Quick start.
  • A harness you have logged into on your own machine:
    • Pi stores its login at ~/.pi/agent/auth.json. Log in with pi, then /login.
    • ChatGPT / Codex uses the same Pi login file. Log in with pi, then /login, and pick the ChatGPT sign-in.
    • Claude Code stores its login at ~/.claude/.credentials.json. Log in with claude and pick the subscription login.

1. Confirm the login on your machine​

Check that the login file exists before you mount it:

# Pi and ChatGPT/Codex
ls ~/.pi/agent/auth.json

# Claude Code
ls ~/.claude/.credentials.json

2. Check that the runner can read it​

The runner container runs as uid 1000. A harness login file is mode 0600 and owned by you, so the container can read it through a bind mount only when your own uid is 1000.

id -u

If that prints 1000, mount your login directly in step 3.

If it prints anything else, the container cannot read the 0600 file, and the run fails as though you had never logged in. In step 3 you run the container as your own user by adding two lines. This mounts your real login directly, so a refreshed token stays in sync between the container and your own machine.

3. Mount the login into the runner​

Edit the runner service in your Compose file (hosting/docker-compose/oss/docker-compose.gh.yml). Add a read-write volume for your login and point the harness at it.

For Pi or ChatGPT/Codex:

runner:
  volumes:
    - ~/.pi/agent:/agenta/harness/pi:rw
  environment:
    PI_CODING_AGENT_DIR: /agenta/harness/pi

For Claude Code:

runner:
  volumes:
    - ~/.claude:/agenta/harness/claude:rw
  environment:
    CLAUDE_CONFIG_DIR: /agenta/harness/claude

If your uid is not 1000 (step 2), also run the container as your own user so it can read the mounted login. Add user: with your id -u:id -g, and set HOME to a writable path. For Claude Code:

runner:
  user: "1001:1001" # your id -u:id -g
  volumes:
    - ~/.claude:/agenta/harness/claude:rw
  environment:
    HOME: /tmp
    CLAUDE_CONFIG_DIR: /agenta/harness/claude

HOME: /tmp is required here. Running as a non-default user sets the container's home directory to a path the harness cannot write, and the harness writes working files under it.

Do not set a provider API key on the runner

A self-managed run inherits the provider keys present in the runner's environment (for example ANTHROPIC_API_KEY or OPENAI_API_KEY), and the harness then authenticates with the key instead of your login. The bundled Compose files set none of them on the runner service. Leave it that way.

The mount is read-write, and the harness runs directly out of it. These are OAuth logins: the harness refreshes its access token during a run and writes the new one back. Because the mount is writable, the refreshed token lands in your login on the host, so runs keep working after the provider rotates a token and you never log in again by hand.

The harness writes other things there too. A run that carries skills or a system prompt installs them into the same directory, and concurrent local runs share it, the same way two pi or claude sessions on your laptop do.

Recreate the runner so it picks up the change:

docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml \
  --env-file hosting/docker-compose/oss/.env.oss.gh up -d runner

4. Run a self-managed agent​

In the studio, run an agent and choose the self-managed credential option (use your own login) for the matching harness. The run authenticates with your mounted subscription instead of a managed key.

If the run fails because the harness has no login, the mount is missing, the runner cannot read it (step 2), or PI_CODING_AGENT_DIR / CLAUDE_CONFIG_DIR does not point at it. Recheck steps 2 and 3.

Next​