Observability and cost control for Claude Code

Key capabilities

How it works

Claude Code normally talks to the Anthropic API directly. Realm's Prism sits in front of that connection: you point Claude Code at the gateway by setting the ANTHROPIC_BASE_URL environment variable. The gateway meters every call, records it, and forwards it on to Anthropic.

Model calls continue to authenticate with your existing credentials, either your Claude login (OAuth) or your ANTHROPIC_API_KEY. The optional LLM_API_KEY you provide to the stack is used only for analysis features such as intent classification and cost saving analysis, never for the Claude Code calls themselves.

Architecture

The stack is defined in docker-compose.yml at the repository root. It runs five long-lived services plus a one-shot migration job.

Request and data flow

Startup order and health

Compose healthchecks enforce a strict startup order: Postgres must be healthy before migrate runs; migrate must complete successfully before the backend starts; and the gateway and frontend wait for a healthy backend. All long-running services are configured to restart unless explicitly stopped.

Requirements

Software

The only external dependency is Docker with Compose. Realm's Prism runs on any cloud provider. A Linux server is the recommended host, though macOS and Windows are supported as well.

Hardware

Realm's Prism is lightweight. Recommended sizing:

Network

• Developers' machines must be able to reach the gateway port (CLAUDE_GATEWAY_PORT).
• Browsers must be able to reach the dashboard port (UI_PORT).
• The host must have outbound access to the Anthropic API.

Note that localhost addresses only work on the machine running the stack. For team or organization-wide use, deploy the gateway on a host your team can reach and use that address (see Connecting Claude Code).

Installation and deployment

1 · Clone the repository

The stack is defined in docker-compose.yml, so you need a local copy of the repository before you can bring it up.

git clone https://github.com/realmlabs-ai/claudecosts.git
cd claudecosts

Run all commands below from inside this claudecosts directory.

2 · Start the stack

LLM_API_KEY=sk-ant-api... CLAUDE_GATEWAY_PORT=9090 UI_PORT=3001 docker compose up -d

This pulls the published images, runs the database migrations, and starts every service in the background. The startup variables are:

Once docker compose up -d finishes, all services should report as running. You can confirm with docker compose ps.

3 · Open the dashboard

With the example ports above, the dashboard is available at:

http://localhost:3001

On a fresh install the dashboard is empty until traffic starts flowing through the gateway (see Connecting Claude Code).

4 · Stop the stack

docker compose down

If you only exported the base URL in a shell, restart your terminal to go back to Anthropic directly. If you made a system, team, or enterprise level change, remove ANTHROPIC_BASE_URL from the local settings.json or managed-settings.json respectively.

Connecting Claude Code

Realm's Prism works by sitting in front of Claude Code: instead of talking to Anthropic directly, Claude Code sends its traffic to the gateway, which meters every call and then forwards it on. The only thing you have to configure on the Claude Code side is the API base URL:

ANTHROPIC_BASE_URL = https://<ADDRESS>:<PORT>

• <ADDRESS> is where the gateway is reachable, for example localhost for a local stack, or your gateway host or domain.
• <PORT> is the gateway port, that is CLAUDE_GATEWAY_PORT from your compose configuration (default 8080).

There are two ways to apply this, depending on whether you are setting it up for yourself or rolling it out across an organization.

export ANTHROPIC_BASE_URL=http://localhost:9090
claude

echo 'export ANTHROPIC_BASE_URL=http://localhost:9090' >> ~/.zshrc

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://<ADDRESS>:<PORT>"
  }
}

{
  "companyAnnouncements": [
    "Realm's Prism Enabled."
  ],
  "env": {
    "ANTHROPIC_BASE_URL": "https://<ADDRESS>:<PORT>"
  }
}

Verify the connection

Run a Claude Code session, then open the Realm's Prism dashboard (UI_PORT, default 3000) and confirm that sessions and costs are showing up.

Disconnect

To stop routing through the gateway, unset the variable (unset ANTHROPIC_BASE_URL) or remove it from your shell profile, settings.json, or the organization's managed-settings.json.

Configuration reference

All configuration is supplied as environment variables consumed by Docker Compose, either inline on the docker compose up command or via the shell environment. In addition to the startup variables in Installation and deployment, the rollup worker accepts the following tuning variables:

Two further variables are internal wiring and require no changes for a standard deployment: DB_DSN_TEMPLATE points the backend, worker, and migration job at Postgres, and BACKEND_UPSTREAM points the frontend at the backend service (backend:8000). Both are set in docker-compose.yml.

Security and privacy

Credentials

The gateway does not replace Claude Code authentication. Model calls continue to use your pre-existing OAuth credentials (Claude login) or ANTHROPIC_API_KEY. The LLM_API_KEY supplied to the stack is used exclusively for analysis features.

Transport

For anything beyond local testing, terminate TLS in front of the gateway and use an https:// base URL.

Network exposure

Only the gateway and dashboard ports are published on the host. Postgres is not published and relies on trust authentication inside the Compose network; do not expose port 5432 externally. Restrict access to the gateway and dashboard ports to your intended users.

Telemetry

To help improve the product, the containers report anonymous, aggregated usage metrics to Realm Labs. This does not include any PII, prompt content, or source code.

Known limitations

The free version is intended for testing and evaluation. Be aware of the following:

• Small-scale testing only. This version is meant for small setups. For larger deployment needs, contact hello@realmlabs.ai and Realm Labs will work with you directly.
• Trace view limitations. The information and metrics shown in the trace view may have some limitations in this version.
• Dashboard data may lag. Data shown in the UI can lag behind live activity by up to a couple of minutes, so recent sessions and metrics may not appear immediately.
• Data is not retained across restarts. Stopping and removing the containers (docker compose down) wipes all stored data.

Troubleshooting

Support and resources

The best place to share feedback, ask questions, and connect with the community is the Realm Labs Discord: discord.gg/6RPjGBEZW. The team is most active there.

• GitHub issues for bugs, unexpected behavior, or feature requests.
• feedback@realmlabs.ai if you would rather reach the team by email.
• hello@realmlabs.ai for larger deployment needs.
• claudecosts.com product website.
• realmlabs.ai Realm Labs company site.

License

Realm's Prism is distributed under the Realm Labs License 1.0. The full license text is available in the LICENSE file at the root of the repository: github.com/realmlabs-ai/claudecosts.

Quick reference

Questions on deployment, configuration, or larger rollouts? Reach the team on Discord or at hello@realmlabs.ai.