# Deploy an AI Agent

Source: https://docs.quake.ai/resources/deployments/deploy-ai-agent
Markdown: https://docs.quake.ai/resources/deployments/deploy-ai-agent.md

---

# Deploy an AI agent

Stand up an AI agent framework on a Quake AI instance using Docker Compose. An agent connects a language model to tools, memory, and external services. You control the model provider, data, and runtime on infrastructure you operate.

<Figure size="md" caption="Agent on a Quake AI instance: the UI brokers between the user, an LLM provider, and tools the model invokes">

```mermaid
sequenceDiagram
    accTitle: AI agent loop on Quake AI
    accDescr: A user prompt reaches the agent on the VM, which calls an LLM, optionally invokes a tool, and returns the response

    participant User
    participant Agent as Agent UI<br/>(Flowise on VM)
    participant LLM as LLM provider<br/>(OpenAI / Ollama)
    participant Tool as Tool / API

    User->>Agent: Prompt
    Agent->>LLM: Plan + chat
    LLM-->>Agent: Tool call request
    Agent->>Tool: Invoke tool
    Tool-->>Agent: Tool result
    Agent->>LLM: Result + chat
    LLM-->>Agent: Final answer
    Agent-->>User: Response
```

</Figure>

<PricingCompanion
  components={[
    { kind: "primitive", required: true, label: "Agent host instance", vm: { flavor: "m2a.large" } },
  ]}
/>

## Prerequisites

- A Quake AI account with an active project
- An SSH key pair added to your project
- An API key from an AI model provider (OpenAI, Anthropic, Google, or [OpenRouter](https://openrouter.ai/) for multi-provider access with a single key), **or** a self-hosted [Ollama](/resources/deployments/run-local-llm) instance

## Choose a framework

| Framework | Best for | Docker image |
|---|---|---|
| [OpenClaw](https://github.com/openclaw/openclaw) | Messaging bots (Telegram, Slack, Discord); 3,200+ community skills | `ghcr.io/openclaw/openclaw` |
| [Flowise](https://flowiseai.com) | Visual agent and RAG pipeline builder | `flowiseai/flowise` |
| [n8n](https://n8n.io) | Workflow automation with AI nodes; connects to 400+ services | `n8nio/n8n` |
| Custom stack | Full control; compose any LLM + tools + memory | N/A |

OpenClaw has a [dedicated guide](/docs/compute/apps/openclaw) with a Console Apps deployment option (**Compute** > **Apps**). The steps below cover the general Docker Compose pattern and walk through Flowise as a concrete example.

## Step 1: Create a VM

<CreateVmConsole flavor="m2a.large" securityPorts="22 (SSH) and 3000 (agent UI; restrict to your IP)" />

Use `m2a.xlarge` if running a local model on the same VM.

## Step 2: Install Docker

<InstallDocker />

## Step 3: Deploy Flowise

Create a project directory:

```bash
mkdir -p ~/flowise && cd ~/flowise
```

Create a `docker-compose.yml`. The steps below were last verified against Flowise 3.1.2; pinning the tag keeps the bootstrap flow predictable, since Flowise has reshaped its auth surface across releases.

```yaml
services:
  flowise:
    image: flowiseai/flowise:3.1.2
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./data:/root/.flowise
    environment:
      - PORT=3000
```

Start the service:

```bash
docker compose up -d
```

Verify it is running:

```bash
docker compose ps
```

Once `docker compose ps` shows the `flowise` container as `Up`, open `http://YOUR_FLOATING_IP:3000` in your browser.

### First-time setup

Flowise 3.x bootstraps an admin account from the browser UI on the first visit. When you open `http://YOUR_FLOATING_IP:3000`, Flowise redirects you to `/signin`. Click **Register** and create the first account using a valid email address. The first account becomes the workspace administrator.

If you need to follow the container output during boot, run `docker compose logs -f flowise` in a separate terminal.

## Step 4: Connect a model provider

In the Flowise UI, navigate to **Credentials** and add your AI provider API key. Flowise supports OpenAI, Anthropic, Google Gemini, Azure OpenAI, and others.

If you are running [Ollama](/resources/deployments/run-local-llm) locally, configure the Ollama node to point to `http://localhost:11434` (or the Ollama VM's private IP if it is on a separate instance).

## Step 5: Build your first flow

In Flowise, create a new **Chatflow**. The basic pattern:

1. Add a **Chat Model** node (e.g., ChatOpenAI, ChatOllama)
2. Add a **Conversational Retrieval QA Chain** or **ReAct Agent** node
3. Add a **Buffer Memory** node for conversation history
4. Connect them and save

Use the built-in chat interface to test your agent before integrating it with an external system.

## Deploying n8n instead

n8n suits automation-first use cases: connecting your agent to webhooks, databases, and external APIs without writing code.

```yaml
services:
  n8n:
    image: n8nio/n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    volumes:
      - ./n8n-data:/home/node/.n8n
    environment:
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=admin
      - N8N_BASIC_AUTH_PASSWORD=change-this-password
      - WEBHOOK_URL=http://YOUR_FLOATING_IP:5678
```

Access the UI at `http://YOUR_FLOATING_IP:5678`. n8n's AI nodes support OpenAI-compatible APIs, which means you can point them at Ollama for local inference.

## Persisting data across restarts

All three frameworks write state to a local directory inside the container. The `volumes` mapping in each compose file ensures that data survives container updates and restarts. Back up the volume directory before updating images:

```bash
docker compose down
cp -r ./data ./data-backup-$(date +%Y%m%d)
docker compose pull
docker compose up -d
```

## Security considerations

**Restrict the UI port.** The default security group in this guide restricts port 3000 to your IP. Avoid opening it to `0.0.0.0/0`. Most frameworks rely on a username/password that is trivial to brute-force over the public internet.

**Keep API keys out of the compose file for production.** Use environment variable files (`.env`) and keep them out of version control, or reference secrets from a vault.

**Run HTTPS in production.** For production deployments, place the agent UI behind a reverse proxy (nginx or Caddy) with a TLS certificate. Use a DNS record pointed at your floating IP.

## Next steps

- [OpenClaw guide](/docs/compute/apps/openclaw): OpenClaw agent framework via Console Apps
- [Run a local LLM](/resources/deployments/run-local-llm): local inference instead of external model providers
- [Deploy Qdrant](/resources/deployments/deploy-vector-database): long-term memory and document retrieval for agents

## Clean up

Stop the compose stack and delete the instance when finished:

```bash
docker compose down
```