Skip to main content

casapi

Stateless HTTP API for remote Claude Code execution powered by Claude Agent SDK.

CI

Each request is one ephemeral claude_agent_sdk.query() run. There are no sessions, no resume, and no server-side conversation state. A client on another machine POSTs a prompt and receives the agent result plus the full message transcript, either as one JSON document or as a Server-Sent Events stream.

Endpoints

Method Path Auth Description
GET /health no Readiness probe: {"status": "ok"}
GET /v1/info yes Server defaults and limits
POST /v1/query yes Run one agent query, return the transcript
POST /v1/query/stream yes Same, streamed as SSE

See docs/api/rest-api.md for the full reference.

Quickstart

Server:

uv sync
export CASAPI_API_KEY="$(openssl rand -hex 32)"
export CASAPI_WORKSPACE_ROOT=/srv/workspaces
export ANTHROPIC_API_KEY=...   # or log in with `claude` as the server user
uv run uvicorn casapi.main:app --host 127.0.0.1 --port 8000

Client (another machine, via TLS or a private network):

curl -sS https://casapi.example.net/v1/query \
  -H "Authorization: Bearer $CASAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "List the files in this directory", "cwd": "myproject", "max_turns": 5}'

curl -N https://casapi.example.net/v1/query/stream \
  -H "Authorization: Bearer $CASAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Summarize README.md"}'

Configuration

Variable Default Description
CASAPI_API_KEY unset Bearer token clients must send
CASAPI_ALLOW_UNAUTHENTICATED false Allow requests with no key configured (local dev only)
CASAPI_WORKSPACE_ROOT current directory All request cwd values must resolve inside this path
CASAPI_DEFAULT_MODEL unset (SDK default) Model used when a request omits model
CASAPI_PERMISSION_MODE acceptEdits Default permission mode
CASAPI_ALLOWED_TOOLS Read,Write,Edit,Bash,Glob,Grep Default auto-approve list (not a restriction; see below)
CASAPI_ALLOW_BYPASS_PERMISSIONS false Permit requests with permission_mode=bypassPermissions
CASAPI_MAX_CONCURRENCY 4 Simultaneous runs; excess requests get HTTP 429
CASAPI_MAX_TIMEOUT_SECONDS 3600 Default and maximum run duration

Security model

  • The API key is a shell. Holding the key is equivalent to running a shell as the service user (with the workspace as the starting directory). Protect it accordingly; everything below is defence in depth, not a sandbox.
  • API key required by default. Without CASAPI_API_KEY (or with an empty one), execution endpoints return 503 unless CASAPI_ALLOW_UNAUTHENTICATED=true is set explicitly. Keys are compared in constant time.
  • allowed_tools is an auto-approve list, not a restriction. It names the tools a run may use without a permission decision; it does not remove other tools, and under the default acceptEdits mode file edits are approved regardless. The server-side CASAPI_ALLOWED_TOOLS is only a default — any key holder can send a different list per request.
  • The agent can read the server's secrets. A run inherits the service environment, including ANTHROPIC_API_KEY, the Claude login credentials, and CASAPI_API_KEY itself. Prompt-injected workspace content can therefore exfiltrate them; do not point the service at untrusted workspaces.
  • Workspace confinement. Request cwd is resolved (symlinks included) and must stay inside CASAPI_WORKSPACE_ROOT. Note this confines the agent's starting directory, not what its tools (e.g. Bash) can reach; run the server as an unprivileged user or in a container for real isolation.
  • bypassPermissions is opt-in via CASAPI_ALLOW_BYPASS_PERMISSIONS. It is not a meaningful boundary on its own: with Bash auto-approved, the default posture is already shell-equivalent.
  • Client disconnects. POST /v1/query promptly cancels the run and frees its concurrency slot when the client disconnects. The streaming endpoint also cancels the run when its consumer goes away.
  • Bind and TLS. Bind to loopback or a private interface and put TLS in front (reverse proxy, Tailscale, or an SSH tunnel). The API key travels in a header.
  • Statelessness. Request bodies containing resume, session_id, or any other unknown field are rejected with 422. Runs are hermetic: CLI session persistence is disabled, so no resumable transcript is written, and host and project settings are not loaded (setting_sources is empty), so hooks or MCP servers from those settings cannot leak into a run. Auto memory is disabled (CLAUDE_CODE_DISABLE_AUTO_MEMORY=1), and MCP configuration is strict and isolated. Managed policy settings and ~/.claude.json still load. The default system prompt is the Claude Code preset. What still persists after a run: files the agent creates or edits in the workspace, and ordinary CLI bookkeeping under ~/.claude.

Development

Requirements: Python 3.11–3.14 and uv.

git clone https://github.com/dceoy/casapi.git
cd casapi
uv sync
uv run uvicorn casapi.main:app --host 127.0.0.1 --port 8000

Swagger UI is at http://127.0.0.1:8000/docs.

uv run ruff format --check .
uv run ruff check .
uv run pyright .
uv run pytest
uv run mkdocs build --strict

Dependency versions are tracked in the committed uv.lock.

License

AGPL-3.0-only. See LICENSE.

Metadata

Release files for casapi 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for casapi 0.2.0
File Size Uploaded Provenance Actions
casapi-0.2.0.tar.gz 26.1 kB With provenance Details for casapi-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for casapi 0.2.0
File Interpreter ABI Platform Actions
casapi-0.2.0-py3-none-any.whl Python 3 none any Details for casapi-0.2.0-py3-none-any.whl

Total release size: 52.3 kB

Release files / casapi-0.2.0.tar.gz

Download URL casapi-0.2.0.tar.gz
Size 26.1 kB
Tags Source
SHA-256 checksum
How to use checksums
22c7c9816af37150e713ecb04ac7b97c5c080aa46b0fdebcb394d715240c1491
BLAKE2b-256 checksum
How to use checksums
f2d28390b6ec0f9b8922230a6c5b8bfb2c509f1ba27f0f713ca8ece59512dc9c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / casapi-0.2.0-py3-none-any.whl

Download URL casapi-0.2.0-py3-none-any.whl
Size 26.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3207d9ccbfdd7471f110e021dc33ac7966db2d71a90486561f1b601027cf370b
BLAKE2b-256 checksum
How to use checksums
8b122f4173726dc602402760f9f2badd4d43974f473d9b31a56979260cfda5e6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for casapi 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for casapi-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page