Skip to main content
Get your first Weaver agent up and running in minutes. This guide will walk you through spawning an agent, interacting with it, and running the gateway for multi-channel support.

​
Prerequisites

Before you begin, ensure you have:
  • Docker installed (version 20.10 or higher)
  • A Gemini API key from Google AI Studio
  • Basic familiarity with command-line tools
Weaver is optimized for the gemini-3-flash-preview model, which offers the best balance of speed and capability for agent tasks.

​
Spawn Your First Agent

The fastest way to get started is by running Weaver in Docker:
1

Set your API key

Export your Gemini API key as an environment variable:
export GEMINI_API_KEY=your_api_key_here
2

Run the agent

Spawn a Weaver agent with a simple task:
docker run --rm \
  -v $(pwd)/workspace:/root/.weaver/workspace \
  -e GEMINI_API_KEY=$GEMINI_API_KEY \
  operatoronline/weaver agent -m "Hello! What can you help me with?"
You should see the agent boot in <1 second and respond to your message.
3

Interactive mode

For a conversational experience, run without the -m flag:
docker run --rm -it \
  -v $(pwd)/workspace:/root/.weaver/workspace \
  -e GEMINI_API_KEY=$GEMINI_API_KEY \
  operatoronline/weaver agent
This starts an interactive shell where you can chat with the agent.

​
What Just Happened?

When you ran the agent:
  1. Fast Boot: Weaver initialized in <1s with <10MB RAM footprint
  2. Workspace Created: A persistent workspace was mounted at ./workspace
  3. Tools Loaded: The agent loaded 15+ built-in tools (file system, shell, web, etc.)
  4. LLM Connected: Connected to Gemini Flash for ultra-fast inference
The workspace directory persists agent memory, skills, and session history. You can inspect ./workspace/sessions/ to see conversation logs.

​
Run the Gateway

For production use or multi-channel support (Telegram, Discord, Slack), run the gateway:
1

Create docker-compose.yml

Create a docker-compose.yml file:
services:
  weaver-gateway:
    image: operatoronline/weaver:latest
    command: gateway
    environment:
      - GEMINI_API_KEY=${GEMINI_API_KEY}
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}  # Optional
      - DISCORD_BOT_TOKEN=${DISCORD_BOT_TOKEN}    # Optional
    volumes:
      - ./workspace:/root/.weaver/workspace
      - ./config.json:/root/.weaver/config.json
    ports:
      - "18790:18790"
    restart: unless-stopped
2

Start the gateway

Launch the gateway service:
docker compose up -d weaver-gateway
The gateway will:
  • Start the agent loop
  • Initialize all configured channels
  • Expose REST API on port 18790
  • Enable cron jobs and heartbeat monitoring
3

Verify it's running

Check the health endpoint:
curl http://localhost:18790/health
You should see:
{
  "status": "healthy",
  "agent_running": true,
  "tools_loaded": 16
}

​
Try Some Commands

Now that your agent is running, try these examples: 
docker run --rm \
  -v $(pwd)/workspace:/root/.weaver/workspace \
  -e GEMINI_API_KEY=$GEMINI_API_KEY \
  operatoronline/weaver agent -m "Create a file called hello.txt with 'Hello, Weaver!'"
Check the workspace:
cat workspace/hello.txt
# Output: Hello, Weaver!

docker run --rm \
  -v $(pwd)/workspace:/root/.weaver/workspace \
  -e GEMINI_API_KEY=$GEMINI_API_KEY \
  operatoronline/weaver agent -m "What Go version is installed?"
The agent will execute go version and report the result.

​
Next Steps

Installation

Install Weaver locally or build from source

Configuration

Customize models, tools, and providers

Multi-Channel Setup

Connect Telegram, Discord, or Slack bots

Skills System

Extend agent capabilities with skills

​
Troubleshooting

  • Verify your API key is correct: echo $GEMINI_API_KEY
  • Check Docker is running: docker ps
  • Ensure the workspace directory has write permissions
  • Weaver is optimized for Gemini Flash. Other providers may be slower.
  • Check your network connection to the LLM provider
  • Monitor the logs: docker compose logs -f weaver-gateway
  • File tools require workspace mount: -v $(pwd)/workspace:/root/.weaver/workspace
  • Web search requires BRAVE_SEARCH_API_KEY environment variable
  • Shell commands run in restricted mode by default (see Configuration)
For more help, visit the FAQ or join the GitHub Discussions.

Build docs developers (and LLMs) love

Get started for freeTalk to us