Security

Credential isolation, access control, and security best practices for AgentStead agents.

How access works

Every agent is protected by credentials. Public URLs require authentication — they're not open endpoints.

Account sessions are authenticated through the dashboard
Agent credentials (username + password + runtime token) are required to access the agent
Secrets are encrypted at rest and masked after saving
Real provider keys never leave AgentStead infrastructure

Your real provider API keys — Anthropic, OpenAI, OpenRouter — never reach your agent container. When you add a key to Secrets, it is stored encrypted in AgentStead infrastructure. At deploy time, AgentStead generates a per-agent proxy token and injects that instead.

Agent container
  ANTHROPIC_API_KEY=x3sproxy_...   ← proxy token, not your real key
         │
         ▼
  proxy.agentstead.dev               ← validates token, fetches + injects real key
         │
         ▼
  api.anthropic.com                ← receives your real key, never the container

From your agent's perspective nothing changes — tools read ANTHROPIC_API_KEY and make API calls normally. The key in the container is a scoped proxy token valid only for that agent and only usable through the proxy.

Real API keys are never written to disk inside the container, never appear in container logs, and are not accessible via environment enumeration or docker inspect.

How it works in detail

Token format: x3sproxy_<32 random chars>. Each token is unique to one agent.

Token rotation: On every deploy or redeploy, the old token is deleted and a new one is generated automatically. A token from a destroyed or redeployed agent is immediately invalid — no manual revocation needed.

Storage: Only a SHA-256 hash of the token is stored in the database, not the token value itself. Even a full database read reveals no usable tokens.

Request flow: When your agent calls an LLM API, the proxy:

Hashes the incoming token and looks it up — no token value is ever persisted in logs
Decrypts the real provider key from the encrypted secret store
Strips the proxy token, injects the real key, forwards the request
Pipes the response back directly — no buffering, no logging of request or response body

Key rotation propagation: Tokens resolved from the database are cached in memory for 60 seconds. If you rotate a key in the dashboard, the old key stops being used within 60 seconds — no agent restart required.

Missing key behaviour: If no key is configured for a provider, the proxy returns 403 with a message pointing to the Secrets tab. The request is not forwarded with a missing or invalid credential.

Your responsibilities

Idle agents with valid credentials are live assets. Destroy agents you no longer need.

Protect credentials

Username, password, and runtime token are enough to access your agent. Don't share them.

Rotate exposed keys

If a provider key is compromised, replace it in the Secrets tab. The proxy picks it up within 60 seconds.

Use Tailscale for private access

Reduces reliance on the public URL for sensitive workflows.

Destroy idle agents

Running agents with valid credentials remain live. Don't leave them around unused.

Tailscale access

When Tailscale is enabled, the agent gets a private IP on your tailnet. This is the preferred path for SSH and any workflow where you don't want to use the public URL.

Your Tailscale auth key is stored as a secret and treated with the same encryption and masking as other secrets.

Account security

Use a strong password for your AgentStead account
GitHub or Google sign-in delegates identity management to those providers
Contact support if you lose access or suspect unauthorised activity