Local Mode — Run Everything on Your Machine

Local mode runs the full Aira stack on your laptop or workstation. No cloud account required. Best for development, debugging, or when you want complete control over your data.

---

When to Use Local Mode

• You are developing or extending aira-agent
• You want to debug MCP tool calls step by step
• You have strict data residency requirements
• You do not want any data leaving your machine

For most users, Managed Remote is simpler and requires no setup.

---

Prerequisites

---

Step 1 — Clone and Configure aira-agent

git clone https://github.com/dimileeh/aira-agent.git
cd aira-agent
cp .env.example .env

Edit .env and set at minimum:

ANTHROPIC_API_KEY=sk-ant-...
DATABASE_URL=postgresql+asyncpg://aira:aira@localhost:5432/aira_dev
JWT_SECRET=your-random-secret-here
ENVIRONMENT=development

---

Step 2 — Start the Stack

docker compose up -d

This starts:

• PostgreSQL 16 on port 5432
• aira-backend (FastAPI) on port 8000

Check everything is running:

curl http://localhost:8000/health
# {"status": "ok"}

---

Step 3 — Run Database Migrations

docker exec aira-backend alembic upgrade head

This creates all 28+ tables required by Aira. Only needed on first run or after pulling new commits.

---

Step 4 — Create a Test Account

curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "yourpassword", "name": "Your Name"}'

Then create a project:

# Get a token first
TOKEN=$(curl -s -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "yourpassword"}' \
  | jq -r '.data.access_token')

# Create a project
curl -X POST http://localhost:8000/api/v1/projects \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Project", "description": "Local test project"}'
# Note the project id from the response

---

Step 5 — Configure Claude Code

Add the local MCP server to Claude Code:

claude mcp add aira-local \
  --transport http \
  --url http://localhost:8000/mcp

Or manually in ~/.claude/claude_desktop_config.json / ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "aira-local": {
      "transport": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

---

Step 6 — Authenticate the MCP Client

The local MCP server uses OAuth. When you first use an Aira MCP tool in Claude Code, it will prompt you to authorize. Visit the URL shown, log in with the account you created in Step 4, and approve access.

Alternatively, generate a long-lived API key and pass it directly:

# Generate an API key via the API
curl -X POST http://localhost:8000/api/v1/auth/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Project-Id: <your-project-id>" \
  -d '{"name": "local-mcp", "scope": "project:admin"}'

Then set it in your MCP client config via a header:

{
  "mcpServers": {
    "aira-local": {
      "transport": "http",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-API-Key": "aira_...",
        "X-Project-Id": "<your-project-id>"
      }
    }
  }
}

---

Step 7 — Test the Connection

In Claude Code:

>> /aira-local list_projects

You should see your project returned. If it works, all MCP tools are available.

---

Available MCP Tools

All tools from the managed remote are available locally. See MCP overview for the full list.

---

Troubleshooting

Connection refused on port 8000 The backend container is not running. Check: docker compose ps and docker compose logs aira-backend.

alembic upgrade head fails The database container may not be ready. Wait 5 seconds and retry. Check: docker compose logs postgres.

401 Unauthorized from MCP tools Your token has expired or the API key is wrong. Re-generate a token or API key (Steps 4–6).

Port conflicts If port 8000 or 5432 is already in use, edit docker-compose.yml to change the host port mapping (e.g. "8001:8000") and update your MCP config URL accordingly.

Changes to aira-agent code not reflected Rebuild the container: docker compose up -d --build aira-backend.

---

Updating

git pull
docker compose up -d --build
docker exec aira-backend alembic upgrade head

---

Next Steps

• MCP tool reference
• Self-hosted remote — if you want to expose your local instance to a team
• aira-agent technical docs — architecture and internals