Connections

Connecting an account

For a subscription, the account holder signs in through the provider’s own sign-in. Ortam keeps the result encrypted, outside every Sandbox, and renews it as it expires. For an API-key account, you give Ortam the key, and it’s stored the same way.

Each Connection names its provider and account, and its status says whether it can be used:

Active

Commands can use it.

Sign-in needed

The provider ended the session, so renewal can’t continue. The account holder signs in again; commands that need it fail before launch until then.

Client restart needed

A client already running in a Sandbox holds credentials that renewal replaced. Restart that client, or the command running it. Ortam never restarts work for you when it can’t tell whether that’s safe.

When Ortam can verify that signing in again, or a rotated key, is for the same account with the same authority, the Connection keeps its identity and grants. A different account, different authority, or one Ortam can’t verify becomes a new Connection, which you grant and select yourself: a Connection never silently switches accounts. A grant you withdrew stays withdrawn either way.

Which Connection a command uses

Each Sandbox has a default Connection, set in its settings. A command uses that one unless it names another with connection_id, and the Connection it names must be granted to the Sandbox. The choice is fixed when the command is accepted: renewal can replace the credentials underneath, but never the account.

curl -X POST "$ORTAM_API/v1/sandboxes/$SANDBOX_ID/executions" \
  -H "Authorization: Bearer $ORTAM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{\"argv\": [\"/bin/bash\", \"-lc\", \"codex exec 'fix the flaky test'\"], \"connection_id\": \"$CONNECTION_ID\"}"

How credentials reach a Sandbox

For subscriptions, Ortam can deliver short-lived credentials; for API-key accounts, it can deliver the key. Delivered credentials live in temporary storage from the moment they arrive, so they’re never part of a save or a Snapshot.

Anything a program copies out of that storage isn’t protected. A token written into a project’s config file is an ordinary file, so it’s saved and copied into Snapshots. A token printed by a command is kept in that command’s output. Neither is filtered.

When an account needs attention, Ortam says so: the account holder may need to sign in again, or the client in the Sandbox may need restarting. A Connection never silently switches to another account. The provider’s own limits and availability still apply, and [supported clients and accounts] are published; an unsupported pairing is refused before launch.

Grants

A new Sandbox gets no credentials. You grant a Connection to a Sandbox explicitly, and the grant covers everything in that Sandbox. Keep work that shouldn’t share credentials in separate Sandboxes.

A command uses its selected Connection or fails before launch. There’s no fallback to another account.

Withdrawing and disconnecting

Withdrawing a grant stops new commands from using it in that Sandbox and stops further deliveries there. Disconnecting a Connection stops renewal and delivery everywhere.