Setup Guide

Prerequisites

• Docker installed and running on your server or laptop. Docker Compose is included with modern Docker installs.
  • Linux server: Install Docker Engine — sudo apt install docker.io docker-compose-v2 (Ubuntu/Debian) or follow the official install guide. Docker runs as a system service and starts automatically on boot.
  • Windows/Mac (local testing): Install Docker Desktop and make sure it's running (check for the Docker icon in your system tray/menu bar).
• An Atlassian account (Cloud or Data Center)
• An AI provider API key — get one from Anthropic, OpenAI, or use Ollama for free local AI
• A Foxbridge license key — get a free 14-day trial

Step 1: Get your license key

1. Go to foxbridge.dev/pricing
2. Click "Start Free Trial" on any plan
3. Enter your work email
4. Copy the license key that appears (it looks like FK-XXXXXXXX-XXXXXXXX-XXXXXXXX)

You'll need this key in the next step.

Step 2: Create a project folder

Create a new folder anywhere on your machine. This is where Foxbridge's configuration will live.

mkdir foxbridge
cd foxbridge

When you're done, the folder will look like this:

foxbridge/
├── foxbridge.yaml          ← your configuration
└── docker-compose.yml   ← Docker Compose file

Step 3: Create foxbridge.yaml

Inside the foxbridge folder, create a file called foxbridge.yaml. Choose the template that matches your Atlassian deployment:

Atlassian Cloud

If your Atlassian is at yourorg.atlassian.net:

license_key: "FK-XXXXXXXX-XXXXXXXX-XXXXXXXX"

atlassian:
  platform: "cloud"
  base_url: "https://yourorg.atlassian.net"
  auth_method: "basic"            # "basic" for email + API token

ai:
  provider: "anthropic"
  api_key: "sk-ant-api03-..."     # your Anthropic API key

features:
  jira:
    read: true
    write: false
  confluence:
    read: true
    write: false
  bitbucket:
    read: true
    write: false

scrub_pii: false                  # set true for regulated industries

Atlassian Data Center (self-hosted)

If your Atlassian runs on your own servers:

license_key: "FK-XXXXXXXX-XXXXXXXX-XXXXXXXX"

atlassian:
  platform: "datacenter"
  base_url: "https://jira.yourcompany.com"
  auth_method: "pat"              # "pat" (recommended) or "basic" (username + password)
  # Optional: if Jira, Confluence, Bitbucket are on different servers
  # jira_url: "https://jira.yourcompany.com"
  # confluence_url: "https://confluence.yourcompany.com"
  # bitbucket_url: "https://bitbucket.yourcompany.com"

ai:
  provider: "anthropic"
  api_key: "sk-ant-api03-..."

features:
  jira:
    read: true
    write: false
  confluence:
    read: true
    write: false
  bitbucket:
    read: true
    write: false

scrub_pii: false

atlassian:
  platform: "datacenter"
  base_url: "https://jira.yourcompany.com"
  auth_method: "pat"
  jira_url: "https://jira.yourcompany.com"
  confluence_url: "https://confluence.yourcompany.com"
  bitbucket_url: "https://bitbucket.yourcompany.com"

What to change in either template:

• license_key — paste the key from Step 1
• base_url — your Atlassian URL
• api_key — your AI provider API key (see AI provider options)

For a full list of every configuration option, see the config reference.

Step 4: Create docker-compose.yml

In the same foxbridge folder, create a file called docker-compose.yml:

services:
  foxbridge:
    image: ghcr.io/foxbridge-ai/foxbridge:latest
    ports:
      - "3000:3000"
      - "3001:3001"
    volumes:
      - ./foxbridge.yaml:/app/foxbridge.yaml:ro
      - foxbridge-data:/var/lib/foxbridge
    restart: unless-stopped

volumes:
  foxbridge-data:

What this does:

• Pulls the Foxbridge Docker image
• Exposes port 3000 (web chat) and 3001 (MCP for IDEs)
• Mounts your foxbridge.yaml into the container (read-only)
• Creates a persistent volume for license cache data

Step 5: Start Foxbridge

From inside the foxbridge folder, run:

docker compose up -d

This downloads the image (first time only) and starts Foxbridge in the background.

Check it's running:

docker compose logs -f

You should see a message like: Foxbridge listening on :3000 (chat) and :3001 (MCP)

Step 6: Open the web chat

1. Open http://localhost:3000 in your browser
2. You'll see the Foxbridge login page
3. Choose how to log in:

• Sign in with Atlassian (Cloud only) — one-click OAuth login, easiest option. Requires OAuth setup.
• API Token (Cloud, auth_method: "basic") — enter your Atlassian email + API token
• Username + Password (Data Center, auth_method: "basic") — enter your DC username and password
• Personal Access Token (both platforms, auth_method: "pat") — enter your PAT. Most secure option for Data Center.

Step 7: Try it out

Type any of these in the chat to get started:

• "Show me open bugs in the PROJ project"
• "Summarize the last 5 comments on PROJ-123"
• "Find Confluence pages about release planning"
• "What pull requests are open in the backend repo?"
• "Create a Jira ticket for fixing the login bug" (requires write: true for Jira)

Updating Foxbridge

To update to the latest version:

docker compose pull
docker compose up -d

Stopping Foxbridge

docker compose down

Your configuration and license cache are preserved. Run docker compose up -d to start again.

Advanced: Connect your IDE (MCP)

Foxbridge exposes an MCP endpoint on port 3001 so you can use it from Claude Code, VS Code, or Cursor.

Claude Code

Add to your MCP settings file:

{
  "mcpServers": {
    "foxbridge": {
      "url": "http://localhost:3001/sse"
    }
  }
}

VS Code / Cursor

Install the MCP extension and add the server URL: http://localhost:3001/sse

Advanced: Air-gapped / Ollama setup

For environments with no internet access, use Ollama as a fully local AI provider. No data ever leaves your network.

1. Install Ollama on the same machine running Docker
2. Pull a model: ollama pull llama3.1
3. Update the ai section of your foxbridge.yaml:

ai:
  provider: "ollama"
  base_url: "http://host.docker.internal:11434"
  model: "llama3.1"

No API key needed. The host.docker.internal hostname lets the Docker container reach Ollama running on your host machine.

Troubleshooting

"License validation failed"

• Check that license_key in foxbridge.yaml matches exactly what you received (no extra spaces)
• Make sure your server can reach foxbridge.dev (try: curl https://foxbridge.dev/api/license/validate?key=YOUR_KEY)
• Foxbridge caches the license for 72 hours, so brief network outages won't affect you

"Atlassian authentication failed"

• Verify your API token or PAT hasn't expired
• For Cloud: make sure you're using your Atlassian email, not your username
• For Data Center: make sure base_url includes the full URL (e.g., https://jira.company.com/jira if Jira is at a context path)

"AI provider errors"

• Check your API key is valid and has credits/quota remaining
• For Azure OpenAI: base_url must be your resource URL and model must be the deployment name (not the model name)
• For Ollama: make sure Ollama is running (ollama serve) and the model is pulled

"failed to connect to the docker API" / "daemon is not running"

• Windows/Mac: Docker Desktop isn't running. Open it from the Start menu or Applications folder and wait for it to fully start.
• Linux: The Docker service isn't running. Start it with sudo systemctl start docker. To make it start on boot: sudo systemctl enable docker.

"Port already in use"

• Another service is using port 3000 or 3001
• Change the ports in docker-compose.yml: "8080:3000" to use port 8080 instead, then visit http://localhost:8080

Still stuck? Contact [email protected]