Installation

Set up your local development environment to build and test agents before deploying to SwiftClaw.

System Requirements

• Node.js: 18.x or later
• Python: 3.9 or later (if using Python agents)
• Git: For repository management
• Operating System: macOS, Linux, or Windows (WSL recommended)

Install SwiftClaw CLI

The SwiftClaw CLI allows you to manage agents, deploy, and monitor from your terminal.

npm install -g swiftclaw-cli

yarn global add swiftclaw-cli

pnpm add -g swiftclaw-cli

Verify installation:

swiftclaw --version

Authentication

Log in to your SwiftClaw account:

swiftclaw login

This will open a browser window for authentication. Once complete, your credentials are stored securely in ~/.swiftclaw/config.

Using API Keys

For automated deployments:

export SWIFTCLAW_API_KEY=your_api_key_here
swiftclaw whoami

Generate API keys in the dashboard under Settings → API Keys.

Install SDK

Install the SwiftClaw SDK for your preferred language:

pip install swiftclaw

poetry add swiftclaw

npm install swiftclaw

yarn add swiftclaw

go get github.com/swiftclaw/swiftclaw-go

Project Setup

swiftclaw init my-agent
cd my-agent

my-agent/
├── swiftclaw.json      # Configuration file
├── agent.py            # Agent code (or agent.ts)
├── requirements.txt    # Dependencies (or package.json)
├── .env.example        # Environment variables template
└── README.md           # Project documentation

{
  "name": "my-agent",
  "version": "1.0.0",
  "runtime": "python3.11",
  "model": {
    "primary": "gpt-4",
    "fallbacks": ["claude-3-sonnet"]
  },
  "memory": {
    "type": "persistent",
    "ttl": "30d"
  },
  "triggers": [
    {
      "type": "api",
      "path": "/chat"
    }
  ],
  "environment": {
    "OPENAI_API_KEY": "${OPENAI_API_KEY}"
  }
}

cp .env.example .env

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

pip install -r requirements.txt

npm install

Local Development

Run your agent locally for testing:

swiftclaw dev

This starts a local development server with:

• Hot reload on code changes
• Local memory storage
• Debug logging
• API endpoint at http://localhost:8000

Testing Locally

Send test requests:

curl http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello, agent!",
    "session_id": "test-session"
  }'

Or use the interactive CLI:

swiftclaw chat --local

IDE Setup

VS Code

Install the SwiftClaw extension:

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "SwiftClaw"
4. Click Install

Features:

• Syntax highlighting for swiftclaw.json
• IntelliSense for SDK functions
• Integrated deployment
• Log streaming

PyCharm / IntelliJ

Install the SwiftClaw plugin:

1. Go to Settings → Plugins
2. Search for "SwiftClaw"
3. Click Install and restart

Verify Installation

Check that everything is set up correctly:

# Check CLI version
swiftclaw --version

# Check authentication
swiftclaw whoami

# Check SDK installation
python -c "import swiftclaw; print(swiftclaw.__version__)"
# or
node -e "console.log(require('swiftclaw').version)"

# Test local development
swiftclaw dev --check

Troubleshooting

CLI Not Found

If swiftclaw command is not found:

# Check if npm global bin is in PATH
npm config get prefix

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$PATH:$(npm config get prefix)/bin"

Authentication Issues

If login fails:

# Clear cached credentials
rm -rf ~/.swiftclaw/config

# Try logging in again
swiftclaw login

SDK Import Errors

If SDK imports fail:

# Verify installation
pip show swiftclaw

# Reinstall if needed
pip uninstall swiftclaw
pip install swiftclaw

# Verify installation
npm list swiftclaw

# Reinstall if needed
npm uninstall swiftclaw
npm install swiftclaw

Next Steps

Now that your environment is set up:

• Deploy Your First Agent - Create and deploy a simple agent
• Core Concepts - Understand SwiftClaw's architecture
• Configuration Reference - Learn all configuration options