Documentation Index
Fetch the complete documentation index at: https://mintlify.com/virsanghavi/axis/llms.txt
Use this file to discover all available pages before exploring further.
Axis is configured entirely through environment variables. For the local MCP server, these are passed through your MCP client’s config file or loaded from a .env.local file during development. For the hosted surface, configuration lives in the Vercel project environment. This page covers every variable the local server and related tooling recognize.
For local development, create a .env.local file at the repo root. The local MCP server walks upward from the working directory to find it. In production, always pass configuration through your MCP client’s mcp.json env block — never rely on .env.local in a deployed or shared setup.
The local MCP server resolves config in this order: (1) env vars from MCP client mcp.json, (2) .env.local walked upward, (3) defaults. In customer deployments, always pass config through mcp.json env vars — never rely on .env.local in production.
Connection and Auth
These variables control which API endpoint the local server connects to and how it authenticates.
| Variable | Required | Description |
|---|
AXIS_API_KEY | Recommended | Bearer token for the hosted API. Defaults the API URL to https://useaxis.dev/api/v1 when set. Also accepted as SHARED_CONTEXT_API_SECRET. Without this variable, the server runs in local/offline mode. |
SHARED_CONTEXT_API_URL | Optional | Override the API endpoint. Defaults to https://useaxis.dev/api/v1 when AXIS_API_KEY is set. Set this only if you are running a self-hosted backend at a different URL. |
- API key set → connects to
https://useaxis.dev/api/v1 (or SHARED_CONTEXT_API_URL if set)
- Neither set → runs free coordination tools in local/offline mode, persisting to
history/nerve-center-state.json
Project Identity
These variables control how the server resolves the current project and org. In most cases, you should not set any of them — rely on .axis/axis.json and repo detection instead.
| Variable | Description |
|---|
AXIS_ORG_ID | Per-machine org override. Overrides the org field in .axis/axis.json. Use when a developer needs to act under a different org than the committed pin, without modifying the committed file. |
AXIS_PROJECT_NAME | Pin project name — overrides repo detection entirely. Do NOT set unless intentional: collapses all repos on the machine onto one board. The most common cause of “why are another repo’s jobs on my board?” |
PROJECT_NAME | Legacy alias for AXIS_PROJECT_NAME. Same behavior and same warning. Prefer AXIS_PROJECT_NAME in new configs. |
AXIS_WORKSPACE_ROOT | Override workspace root for project detection. Also accepted from agent env as SUPERSET_WORKSPACE_PATH or SUPERSET_ROOT_PATH. Use when the agent host does not expose its working directory through standard means. |
Supabase (Direct Mode, Dev Only)
These variables enable direct Supabase mode, where the local server bypasses the hosted API and calls Supabase RPCs directly. For development and testing only.
| Variable | Description |
|---|
NEXT_PUBLIC_SUPABASE_URL | Supabase project URL. Used only when not in remote API mode (i.e., when AXIS_API_KEY is not set). |
SUPABASE_SERVICE_ROLE_KEY | Full-access Supabase key that bypasses RLS. Server-side only — never expose this in a browser context or commit it to source control. It is the highest-privilege secret in the system. |
Lock Enforcement
| Variable | Description |
|---|
AXIS_ENFORCE_LOCKS | Set to 1 to enable physical lock enforcement. When active, the server chmods locked files read-only on grant, so any process — including agents that ignore Axis — receives EACCES on write attempts. The lock holder writes through guarded_write, which briefly restores permissions. Locks are restored to their original mode on release_file_access, complete_job, or finalize_session. Advisory-only by default; this option changes editing ergonomics so it is off unless explicitly opted in. |
- A process running as the same OS user can still
chmod the file back — no userspace server can prevent that
guarded_write is the correct write path while a file is physically locked- A server crash while enforcement is active can leave files in read-only mode;
force_unlock or manually running chmod restores them
Session Transcripts
Axis records every Axis MCP tool call and result at the protocol boundary with any client. These variables extend that to include the full user/assistant chat transcript from the agent host, when available.
| Variable | Description |
|---|
AXIS_TRANSCRIPT_PATH | Absolute path to an agent’s session transcript file (JSONL or JSON). Axis reads this file at session finalization and merges it into the archived session. |
AXIS_TRANSCRIPT_FORMAT | Format of the transcript file: codex, claude, or generic. Claude Code and Codex are detected automatically without this variable. Set generic for any other client that exports a JSON/JSONL transcript. |
AXIS_AGENT_BASE | Agent identifier string for transcript attribution (e.g. github-copilot, windsurf). Appears in the session archive alongside the tool call timeline. |
{
"env": {
"AXIS_TRANSCRIPT_PATH": "/absolute/path/to/session.jsonl",
"AXIS_TRANSCRIPT_FORMAT": "generic",
"AXIS_AGENT_BASE": "github-copilot"
}
}
role/content, messages, tool_calls, tool_call, and tool_result shapes. MCP cannot access chat text a host keeps private — in that case, Axis still captures the complete Axis tool call timeline.
Other
| Variable | Description |
|---|
OPENAI_API_KEY | Required for hosted embeddings and LLM reranking. Server-side only — not needed for the local server running in offline mode, and never exposed to clients. |
AXIS_SKIP_SUBSCRIPTION_CHECK | Set to 1 to skip subscription validation. Useful for local testing and development when a valid Axis subscription is not available. |
Local Development: .env.local Example
# .env.local — for local development only, never commit this file
# Connect to the hosted API
AXIS_API_KEY=sk_sc_your_key_here
# Or override to a local backend
SHARED_CONTEXT_API_URL=http://localhost:3000
# Direct Supabase mode (dev only — skip if using AXIS_API_KEY)
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
# OpenAI for embeddings (server-side only)
OPENAI_API_KEY=sk-your-openai-key
.env.local is covered by .gitignore. Never commit secrets to source control.
Production: mcp.json env Block
In production, pass all configuration through the MCP client’s config file. This is the canonical path — .env.local is a development convenience only.
{
"mcpServers": {
"axis": {
"command": "npx",
"args": ["-y", "@virsanghavi/axis-server"],
"env": {
"AXIS_API_KEY": "sk_sc_your_key_here"
}
}
}
}
.axis/axis.json:
{
"mcpServers": {
"axis": {
"command": "npx",
"args": ["-y", "@virsanghavi/axis-server"],
"env": {
"AXIS_API_KEY": "sk_sc_your_key_here",
"AXIS_ORG_ID": "org_abc123"
}
}
}
}