> ## Documentation Index
> Fetch the complete documentation index at: https://condor.hummingbot.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Installing Condor and Hummingbot API

> Deploy the two-server architecture

Condor uses a [two-server architecture](/motivation): the **Condor Server** (agentic layer) and the **Hummingbot API Server** (execution layer). This guide installs both.

<Warning>
  **Secure your API before going live.** Hummingbot API can place orders, read balances, and manage bots. AI assistants (MCP, Condor agents, and similar tools) make that surface easier to reach—and easier to misuse if the API is open on the public internet.

  **We recommend [Tailscale](#secure-remote-access-with-tailscale) for production**, especially when Condor and the API run on different machines. Tailscale puts the API on a private encrypted network so only your devices can connect—without publishing port **8000** on a public IP. Use strong API passwords too; Tailscale is network isolation on top of auth, not a replacement for it.

  Full walkthrough: [Securing Condor and Hummingbot API with Tailscale](https://hummingbot.org/blog/posts/securing-condor-and-hummingbot-api-with-tailscale/) · [Hummingbot API Tailscale guide](https://hummingbot.org/hummingbot-api/tailscale/)
</Warning>

## Prerequisites

<AccordionGroup>
  <Accordion title="System Requirements">
    | Component | Minimum                                 | Recommended      |
    | --------- | --------------------------------------- | ---------------- |
    | OS        | Linux x64 or ARM (Ubuntu 20.04+), macOS | Ubuntu 22.04 LTS |
    | Memory    | 4 GB RAM                                | 8 GB RAM         |
    | Storage   | 10 GB SSD                               | 20 GB SSD        |
    | CPU       | 2 vCPUs                                 | 4 vCPUs          |
  </Accordion>

  <Accordion title="Cloud Server Options">
    Any cloud provider works. Popular choices:

    * **AWS EC2**: t3.medium or larger
    * **Google Cloud**: e2-medium or larger
    * **Digital Ocean**: Basic Droplet with 4GB RAM
    * **Hetzner**: CX21 or larger

    Allow **SSH (port 22)** for administration. **Do not expose port 8000 publicly** for production—use [Tailscale](#secure-remote-access-with-tailscale) so Condor and other clients reach the API at `http://hummingbot-api:8000` on your private tailnet.
  </Accordion>

  <Accordion title="Tailscale (recommended for production)">
    Create a free account at [tailscale.com](https://tailscale.com), then:

    1. Generate a **reusable** auth key at [Settings → Keys](https://login.tailscale.com/admin/settings/keys) (starts with `tskey-auth-`)
    2. Enable **[MagicDNS](https://login.tailscale.com/admin/dns)** so `hummingbot-api` resolves by name
    3. Install Tailscale on any device that should reach the API (your laptop, Condor host, etc.) and sign in to the same account

    During Hummingbot API setup, answer **`y`** when asked to enable Tailscale.
  </Accordion>
</AccordionGroup>

## Quick Install

<Tabs>
  <Tab title="Quick Start">
    From an empty directory:

    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/hummingbot/deploy/main/setup.sh | bash
    ```
  </Tab>

  <Tab title="Hummingbot API only">
    Use this **only** if you still need the API and database stack **by itself**—for example the Quick Start script **did not** install Hummingbot API (you skipped it or something failed), or you are deploying the API on a **separate** machine (VPS, etc.). **Docker** must be running on that host before you run the command.

    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/hummingbot/deploy/main/setup.sh | bash -s -- --hummingbot-api
    ```

    On a VPS or remote server, **enable Tailscale when prompted** (answer **`y`**) so Condor and other clients can reach the API privately.
  </Tab>

  <Tab title="Manual install">
    **Note:** Prefer **Quick Start** above. Use manual install **only** if the deploy script fails or you are intentionally setting up from source (for example development).

    Clone the Condor repo and use the Makefile. You still need a running **Hummingbot API** (for example [Docker with hummingbot-api](https://github.com/hummingbot/hummingbot-api)) unless you already have one.

    ```bash theme={null}
    git clone https://github.com/hummingbot/condor.git
    cd condor

    make install     # Interactive setup + dependencies + AI CLI tools
    make run         # Start the bot
    ```
  </Tab>
</Tabs>

Interactive setup will prompt for:

* **Telegram Bot Token**: Create one via [@BotFather](https://t.me/botfather)
* **Telegram User ID**: Get yours via [@userinfobot](https://t.me/userinfobot)
* Whether to **configure and launch Hummingbot API** with Docker—answer **yes** if you are deploying **Condor and the API on the same machine** locally. Have **[Docker](https://docs.docker.com/get-docker/)** installed and running first. If the API runs on another server, you can skip this step and add that API URL later in Telegram under **`/servers`**.
* **Tailscale** (when installing Hummingbot API): answer **`y`** for production or any remote setup; paste your `tskey-auth-...` key when prompted

## Create a Telegram Bot

1. Open [@BotFather](https://t.me/botfather) in Telegram
2. Send `/newbot` and follow the prompts to name your bot
3. Copy the bot token (format: `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`)

## Get Your User ID

1. Open [@userinfobot](https://t.me/userinfobot) in Telegram
2. Send `/start` to receive your user ID

## Secure Remote Access with Tailscale

Use Tailscale when Condor and Hummingbot API run on **different machines**—for example Condor on your laptop and the API on a cloud VPS.

### On the API server

1. Run the **Hummingbot API only** installer (or Quick Start with API enabled)
2. When asked **Use Tailscale for secure private networking?**, answer **`y`**
3. Paste your auth key and deploy:

```bash theme={null}
cd hummingbot-api
make deploy
make tailscale-status   # confirm hummingbot-api appears on your tailnet
```

### On the Condor machine

1. Install [Tailscale](https://tailscale.com/download) and sign in to the **same account**
2. In Telegram, open **`/servers`** and add the API with:
   * **Host**: `hummingbot-api` (MagicDNS name, not a public IP)
   * **Port**: `8000`
   * **Username / Password**: same as the API `.env`

Test from the Condor host:

```bash theme={null}
curl -u YOUR_USERNAME:YOUR_PASSWORD http://hummingbot-api:8000/health
```

<Tip>
  Tailscale also works when Condor and the API run on the **same machine**—you still get a stable hostname and avoid publishing port 8000 publicly.
</Tip>

## Verify Installation

1. Open your Telegram bot and send `/start`
2. You should see the main menu with commands like `/portfolio`, `/trade`, `/agent`

> **Note:** After Condor starts successfully, **admins** should receive a Telegram message: **"Condor is online and ready."** If that does not appear within a minute or two, check the troubleshooting section below (for example attach to the `condor` tmux session after Quick Start).

```
Welcome to Condor! 🦅

Commands:
/portfolio - View balances
/trade - Place orders
/agent - Trading Agents
/keys - Manage credentials
/servers - API servers
```

## Access Points

| Service       | Local URL                    | Tailnet URL (when Tailscale enabled) | Description       |
| ------------- | ---------------------------- | ------------------------------------ | ----------------- |
| Telegram      | Your bot                     | —                                    | Primary interface |
| API           | `http://localhost:8000`      | `http://hummingbot-api:8000`         | REST API          |
| Swagger       | `http://localhost:8000/docs` | `http://hummingbot-api:8000/docs`    | API documentation |
| Web Dashboard | Run `/web` in Telegram       | —                                    | Browser interface |

## Managing Services

How you manage Condor depends on how you installed it.

**After Quick Start (deploy installer):** Condor runs in a **tmux** session named `condor`.

```bash theme={null}
tmux attach -t condor    # live logs and tracebacks (detach: Ctrl+B, then D)
tmux kill-session -t condor   # stop Condor completely
```

From the directory that contains the `condor` folder, you can also upgrade with:

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/hummingbot/deploy/main/setup.sh | bash -s -- --upgrade
```

**After Manual install:** Condor runs in the foreground of the terminal where you ran `make run` (stop with **Ctrl+C**). Watch that terminal, or run under `tmux` yourself if you want a detachable session.

**Hummingbot API (Docker):** From the `hummingbot-api` directory (sibling of `condor` when installed by the deploy script):

```bash theme={null}
docker compose ps
docker compose logs -f   # or your compose plugin equivalent
make tailscale-status    # when Tailscale is enabled
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Bot not responding in Telegram">
    1. **Confirm the process is running**
       * *Quick Start / deploy:* `tmux attach -t condor` and look for tracebacks or exit messages.
       * *Manual install:* Check the terminal where `make run` is running.
    2. **Check `condor/.env`** on the machine that runs Condor: `TELEGRAM_TOKEN` must match [@BotFather](https://t.me/botfather), and `ADMIN_USER_ID` must be your numeric Telegram user id (from [@userinfobot](https://t.me/userinfobot)).
    3. **Access still pending:** New users must be approved. An admin should use **`/admin`** (or the admin flow from **`/start`**) to approve you.
    4. **Deploy installer hint:** If admins never see *"Condor is online and ready."*, attach to tmux (above) and fix errors shown there; the installer also reminds you to verify `.env` when that message is missing.
  </Accordion>

  <Accordion title="Active server is offline / Cannot reach server / API errors in commands">
    Condor talks to the **Hummingbot API** over HTTP using the **host**, **port**, **username**, and **password** stored for each server (see **`/servers`** in Telegram or `condor/config.yml`). Status checks call `http://{host}:{port}` and list accounts; failures surface as **Offline** (*Cannot reach server*, *Connection timeout*) or **Auth Error** (*Invalid credentials*).

    1. **Is the API stack up?** On the machine where Docker runs the API: `docker compose ps` (from the `hummingbot-api` repo directory). You want the API container healthy and port **8000** (default) listening.
    2. **Smoke test from the Condor host:** `curl -sS -o /dev/null -w "%{http_code}" http://127.0.0.1:8000/docs` (same machine) or `curl -u USER:PASS http://hummingbot-api:8000/health` (Tailscale). You should get **200**. If this fails, Condor will show offline until the API is reachable.
    3. **Wrong host for your layout**
       * API and Condor on the **same** machine: `host` is usually `localhost` or `127.0.0.1`.
       * API on a **different** host or VPS: use **`hummingbot-api`** (MagicDNS) when Tailscale is enabled—not a public IP and not `localhost` (localhost would point at the Condor machine itself).
       * **Docker Desktop / WSL:** If Condor runs in one environment and the API in another, `localhost` may not cross namespaces; use the host gateway IP or publish ports and use the reachable address from Condor's network namespace.
    4. **Tailscale / firewall:** Prefer Tailscale over opening port **8000** on a public firewall. If you must use a public IP, allow inbound **8000** only from the Condor host—but [Tailscale is strongly recommended](https://hummingbot.org/hummingbot-api/tailscale/) instead.
    5. **Credentials:** **Auth Error** means HTTP **401**—username/password in **`/servers`** must match the API's HTTP basic auth (the deploy flow syncs `config.yml` with `hummingbot-api/.env` when both are installed together; if you changed one side, align the other or re-save in **`/servers`**).
  </Accordion>

  <Accordion title="No servers configured / Server not found / No servers available">
    * **`/servers`** shows *No servers configured* until at least one entry exists in **`condor/config.yml`** under `servers:` (and users need **access** to a server—admins own new entries; others must be **shared**).
    * **Server not found** in the UI usually means the configured server name does not exist anymore (typo after edit, or deleted entry)—open **`/servers`**, pick a valid server, or add one again.
    * **No servers available** (errors when running commands) often means your user has no server shared with them—ask an **owner** admin to share a server with your Telegram user id.
    * After **Manual install**, you must add the real API URL (and auth) via **`/servers`** if `config.yml` was not pre-filled.
  </Accordion>

  <Accordion title="Docker or installer problems (API did not start)">
    1. **Docker daemon:** The deploy script checks that Docker is running before bringing up the API. On Linux: `docker info`. On Mac/Windows: open **Docker Desktop** and wait until it is fully started.
    2. **Compose:** You need either `docker compose` (plugin) or legacy `docker-compose` (the installer checks this).
    3. **API-only recovery:** If Quick Start skipped or failed the API step, use the **Hummingbot API only** tab command, or from `hummingbot-api`: `make setup`, `docker compose pull`, `make deploy` (see [hummingbot-api](https://github.com/hummingbot/hummingbot-api) README).
    4. **Sibling layout:** Condor's setup wizard expects **`hummingbot-api`** next to **`condor`** (`../hummingbot-api` from the Condor directory) when both are installed by the same flow—keep that layout unless you know how to point `config.yml` at a custom URL.
  </Accordion>

  <Accordion title="Tailscale not connecting">
    | Problem                             | Try this                                                                               |
    | ----------------------------------- | -------------------------------------------------------------------------------------- |
    | Name `hummingbot-api` does not work | Enable **MagicDNS** in [Tailscale DNS settings](https://login.tailscale.com/admin/dns) |
    | Auth key rejected                   | Key must start with `tskey-auth-`; generate a new one if it expired                    |
    | Connection refused                  | On the API server: `make tailscale-status` and `make deploy` again                     |
    | Login fails (401)                   | Use the same username/password as in the API `.env`                                    |
    | Still reachable on public IP        | Remove port **8000** from your cloud provider's firewall / security group              |

    See also: [Hummingbot API Tailscale guide](https://hummingbot.org/hummingbot-api/tailscale/)
  </Accordion>
</AccordionGroup>

## Next Step

<Card title="Adding Credentials" icon="arrow-right" href="/getting-started/credentials">
  Connect your exchange accounts
</Card>