Skip to content

getting-started.md

Latest commit

 

History

History
237 lines (169 loc) · 6.87 KB

getting-started.md

File metadata and controls

237 lines (169 loc) · 6.87 KB

Getting Started with Aegis

Get from zero to orchestrating Claude Code sessions in under 5 minutes.

Prerequisites

Requirement Minimum Version Check Command
Node.js ≥ 20 node --version
Claude Code CLI Latest claude --version
tmux ≥ 3.2 tmux -V

Windows users: Install psmux instead of tmux. See Windows Setup for details.

1. Start Aegis

No install required — run directly with npx:

npx @onestepat4time/aegis

Aegis starts on http://localhost:9100. Verify it's running:

curl http://localhost:9100/v1/health
Install globally (optional) 
npm install -g @onestepat4time/aegis
aegis
Docker (alternative) 
docker run -it --rm \
  -v $(pwd):/workspace \
  -p 9100:9100 \
  node:20-slim bash -c "apt-get update && apt-get install -y tmux > /dev/null 2>&1 && npm install -g @anthropic-ai/claude-code && npx @onestepat4time/aegis"

Docker requires Claude Code CLI to be installed and authenticated inside the container.

Start with authentication

Set a bearer token to protect all endpoints (except /v1/health):

AEGIS_AUTH_TOKEN=your-secret-token npx @onestepat4time/aegis

Then include the token in every request:

curl -H "Authorization: Bearer your-secret-token" http://localhost:9100/v1/sessions

2. Open the Dashboard

Visit http://localhost:9100/dashboard/ in your browser. The dashboard shows all sessions, their status, and activity in real time.

No extra setup needed — the dashboard is built into Aegis.

3. Create Your First Session

curl -X POST http://localhost:9100/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "name": "explore-project",
    "workDir": "/path/to/your/project",
    "prompt": "Analyze this project. List the main technologies, directory structure, and any issues you spot."
  }'

The response includes the session ID:

{
  "id": "a1b2c3d4",
  "name": "explore-project",
  "status": "working",
  "workDir": "/path/to/your/project"
}

Save the id — you'll need it for follow-up commands.

4. Monitor Progress

Watch the session in the dashboard, or poll the API:

curl http://localhost:9100/v1/sessions/a1b2c3d4

For real-time updates, use the SSE event stream:

curl -N http://localhost:9100/v1/events

5. Send a Follow-Up

curl -X POST http://localhost:9100/v1/sessions/a1b2c3d4/send \
  -H "Content-Type: application/json" \
  -d '{"text": "Now create a detailed plan to fix the issues you found."}'

6. Read the Results

curl http://localhost:9100/v1/sessions/a1b2c3d4/read

This returns the parsed transcript — Claude Code's full response in structured JSON.

7. Handle Permission Prompts

When Claude Code asks for approval (e.g., to run a shell command or write a file), the session status changes to permission_prompt. Approve or reject:

# Approve
curl -X POST http://localhost:9100/v1/sessions/a1b2c3d4/approve

# Reject
curl -X POST http://localhost:9100/v1/sessions/a1b2c3d4/reject

You can also set permissionMode when creating a session to control approval behavior:

Mode Behavior
default Prompts for dangerous operations (recommended)
bypassPermissions Auto-approves everything (use with caution)

8. Run Multiple Sessions in Parallel

Aegis is designed for parallel orchestration. Each session runs in its own tmux window:

# Backend fix
curl -X POST http://localhost:9100/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{"name": "backend", "workDir": "/path/to/backend", "prompt": "Fix failing API tests"}'

# Frontend improvement
curl -X POST http://localhost:9100/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{"name": "frontend", "workDir": "/path/to/frontend", "prompt": "Add loading states to all API calls"}'

# Documentation
curl -X POST http://localhost:9100/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{"name": "docs", "workDir": "/path/to/project", "prompt": "Update README with the new API endpoints"}'

List all sessions:

curl http://localhost:9100/v1/sessions

9. Set Up MCP Integration

Connect Aegis to Claude Code for native tool access:

claude mcp add aegis -- npx @onestepat4time/aegis mcp

This registers 24 MCP tools (session management, transcript reading, pipeline orchestration, etc.). Restart Claude Code to load the tools.

For the full MCP tools reference, see MCP Tools.

Configuration

Aegis is configured via environment variables:

Variable Default Description
AEGIS_PORT 9100 HTTP server port
AEGIS_HOST 127.0.0.1 Bind address
AEGIS_AUTH_TOKEN (empty) Bearer token (empty = no auth)
AEGIS_STATE_DIR ~/.aegis State directory
AEGIS_LOG_LEVEL info Log verbosity

Or use a config file (aegis.config.json):

{
  "port": 9100,
  "authToken": "your-token",
  "memoryBridge": {
    "enabled": true
  }
}

For the full configuration reference, see Enterprise Deployment.

Next Steps

Troubleshooting

Problem Solution
tmux: command not found Install tmux: sudo apt install tmux (Ubuntu) or brew install tmux (macOS)
Claude Code CLI not found Install Claude Code: npm install -g @anthropic-ai/claude-code and run claude to authenticate
401 Unauthorized Set AEGIS_AUTH_TOKEN or include Authorization: Bearer <token> header
Session stuck on stalled Send an interrupt: curl -X POST http://localhost:9100/v1/sessions/:id/interrupt
MCP tools not showing in Claude Code Re-run claude mcp add aegis -- npx @onestepat4time/aegis mcp and restart Claude Code
Dashboard won't load Verify Aegis is running on port 9100: curl http://localhost:9100/v1/health
EADDRINUSE on startup Port 9100 is in use. Set a different port: AEGIS_PORT=9200 npx @onestepat4time/aegis
Screenshot returns 501 Install Playwright: npx playwright install chromium
No output from /read Wait for transcript entries, or check raw terminal: curl /v1/sessions/:id/pane