HQ

https://docs.yourhq.ai
Admin
HQ is a self-hosted AI operations workspace for managing persistent agents, CRM, tasks, knowledge,...
Tokens:104,567
Snippets:1,636
Trust Score:2.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Development Setup - Running Just the UI

Source: https://docs.yourhq.ai/development/contributing

Installs dependencies and starts the UI development server.

```bash
cd apps/ui
npm install --legacy-peer-deps
npm run dev
```

--------------------------------

### Manual Gateway Installation Steps

Source: https://docs.yourhq.ai/self-host/installation

Steps for manually setting up the gateway on a separate machine, including cloning the repository, configuring environment variables, installing Tailscale, and starting the gateway service using Docker Compose.

```bash
docker compose --profile gateway up -d
```

--------------------------------

### Manual Install (Inspect Code)

Source: https://docs.yourhq.ai/getting-started/quickstart

If you prefer to inspect the code first, you can clone the repository and run it manually.

```bash
git clone https://github.com/yourhq/yourhq.git
cd yourhq
cp .env.example .env
docker compose up -d ui
```

--------------------------------

### Install HQ

Source: https://docs.yourhq.ai/getting-started/quickstart

Run this command in your terminal to install HQ. The installer will ask a couple of questions.

```bash
curl -fsSL install.yourhq.ai | bash
```

--------------------------------

### Development Setup - Full Project

Source: https://docs.yourhq.ai/development/contributing

Clones the repository, sets up environment variables, and starts the development environment using Docker Compose.

```bash
git clone https://github.com/yourhq/yourhq.git
cd yourhq
cp .env.example .env
# Leave Supabase empty for browser onboarding, or set env overrides for gateway-only testing

docker compose -f docker-compose.yml -f docker-compose.dev.yml up
```

--------------------------------

### Install the CLI

Source: https://docs.yourhq.ai/development/docs

Install the Mintlify CLI globally.

```bash
npm i -g mint
```

--------------------------------

### Tailscale Installation and Configuration

Source: https://docs.yourhq.ai/self-host/networking

Commands to install Tailscale, start the service with an auth key, and configure the hostname. It also shows how to access YourHQ AI via its Tailscale IP.

```bash
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up --authkey=<your-key> --hostname=yourhq-$(hostname) --accept-routes
# reads back the assigned IP and writes it into HOST_REACHABLE_URL
```

--------------------------------

### Topology B: UI on Laptop, Gateway on VPS - Laptop Setup

Source: https://docs.yourhq.ai/self-host/networking

Commands to set up the UI on a laptop, cloning the repository, configuring .env, and starting the UI service.

```bash
git clone https://github.com/yourhq/yourhq.git && cd yourhq
cp .env.example .env
# fill in Supabase, then:
# GATEWAY_URL points at the VPS over Tailscale
sed -i '' 's|GATEWAY_URL=.*|GATEWAY_URL=http://100.x.y.z:18790|' .env
docker compose up -d ui
```

--------------------------------

### Clone and setup yourhq repository

Source: https://docs.yourhq.ai/development/local-development

Clones the yourhq repository, navigates into the directory, and copies the example environment file.

```bash
git clone https://github.com/yourhq/yourhq.git
cd yourhq
cp .env.example .env
```

--------------------------------

### Download, inspect, and run the installer script

Source: https://docs.yourhq.ai/security/security-policy

For production installs, it's recommended to download the installer script first, inspect its contents, and then execute it. This provides an opportunity to review the script before it runs on your system.

```bash
curl -fsSL install.yourhq.ai -o install.sh
less install.sh
bash install.sh
```

--------------------------------

### Development Setup - Running Just the Gateway

Source: https://docs.yourhq.ai/development/contributing

Starts the gateway, dispatcher, and runner services in detached mode and follows the gateway logs.

```bash
docker compose up -d gateway dispatcher runner
docker compose logs -f gateway
```

--------------------------------

### Gateway Installer Script

Source: https://docs.yourhq.ai/self-host/installation

This command downloads and executes the gateway installer script. It passes necessary environment variables for authentication and configuration. The script checks for Docker, sets up the .env file, pulls Docker images, and starts the gateway service.

```bash
curl -fsSL https://install.yourhq.ai/gateway \
  | GATEWAY_TOKEN='...' SUPABASE_URL='...' ... bash
```

--------------------------------

### Start gateway services

Source: https://docs.yourhq.ai/reference/docker-services

For single-host installs, start everything with `docker compose --profile gateway up -d`. For multi-host setups, run `docker compose up -d ui` separately from the gateway services.

```bash
docker compose --profile gateway up -d
docker compose up -d ui
```

--------------------------------

### Topology B: UI on Laptop, Gateway on VPS - VPS Setup

Source: https://docs.yourhq.ai/self-host/networking

Commands to set up the gateway, dispatcher, runner, and embedder on a VPS, including installing HQ host-level networking and configuring .env.

```bash
# Install the HQ host-level networking — Tailscale joined to your tailnet
curl -fsSL https://raw.githubusercontent.com/yourhq/yourhq/main/installer/install.sh | bash
# Pick Tailscale, provide auth key, then when it starts services:
# edit .env to set GATEWAY_ID=vps-gateway and run without ui
docker compose --profile gateway up -d
```

--------------------------------

### Linear Sync Plugin Example

Source: https://docs.yourhq.ai/guides/plugins

A Python example demonstrating how to create a local plugin for synchronizing tasks with Linear.

```python
class Handler(BasePlugin):
    def on_event(self, event: PluginEvent) -> PluginResponse | None:
        if event.event_type == "task.created":
            api_key = self.ctx.secrets.resolve("LINEAR_API_KEY")
            team_id = self.ctx.config.get("linear_team_id")
            # Create Linear issue via API
            # Store mapping: HQ task ID 
            self.ctx.state.set(
                f"linear_{event.entity_id}",
                {"linear_id": issue_id},
                scope_kind="task",
                scope_id=event.entity_id,
            )
        elif event.event_type == "task.completed":
            mapping = self.ctx.state.get(
                f"linear_{event.entity_id}",
                scope_kind="task",
                scope_id=event.entity_id,
            )
            if mapping:
                # Update Linear issue to "Done"
                pass
        return None
```

--------------------------------

### Re-run Tailscale Host Install

Source: https://docs.yourhq.ai/troubleshooting/common-issues

Install or re-install Tailscale on the host machine.

```bash
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up --authkey=tskey-auth-... --hostname="yourhq-$(hostname)"
```

--------------------------------

### Public HTTPS Setup Instructions

Source: https://docs.yourhq.ai/self-host/networking

Steps to configure YourHQ AI for Public HTTPS access, involving running the installer and setting up a reverse proxy separately.

```bash
# 1. Run the installer and pick "Public HTTPS"
# 2. Enter your domain when prompted
# 3. Install + configure a reverse proxy separately (see §7)
```

--------------------------------

### Real-Host Validation Install Script

Source: https://docs.yourhq.ai/development/testing

Installs the YourHQ system on a fresh VPS using a curl script.

```bash
curl -fsSL https://raw.githubusercontent.com/yourhq/yourhq/main/installer/install.sh | bash
```

--------------------------------

### GIT_REMOTE_URL Examples

Source: https://docs.yourhq.ai/reference/configuration

Examples of different formats for the GIT_REMOTE_URL configuration.

```env
GIT_REMOTE_URL=https://x-access-token:$TOKEN@github.com/org/repo.git
```

```env
GIT_REMOTE_URL=git@github.com:org/repo.git
```

```env
GIT_REMOTE_URL=https://git.example.com/agents.git
```

--------------------------------

### TEMPLATES_SOURCE Example

Source: https://docs.yourhq.ai/reference/configuration

Example of overriding the default template source with a Git repository.

```env
TEMPLATES_SOURCE=git+https://github.com/your-org/your-templates.git
```

--------------------------------

### Directly run the installer script

Source: https://docs.yourhq.ai/troubleshooting/common-issues

If the bash pipe install doesn't show prompts, clone the repo and run the script directly for guaranteed interactive prompts.

```bash
git clone https://github.com/yourhq/yourhq.git
cd yourhq
./installer/install.sh
```

--------------------------------

### Start gateway services

Source: https://docs.yourhq.ai/self-host/add-gateway

Start the gateway, dispatcher, and runner services using Docker Compose.

```bash
docker compose up -d gateway dispatcher runner
```

--------------------------------

### GIT_DEPLOY_KEY Example

Source: https://docs.yourhq.ai/reference/configuration

Example of setting the GIT_DEPLOY_KEY for SSH remotes. Note the surrounding double-quotes to preserve newlines.

```env
GIT_DEPLOY_KEY="-----BEGIN OPENSSH PRIVATE KEY-----\n...
-----END OPENSSH PRIVATE KEY-----"
```

--------------------------------

### GITHUB_* Variables Example

Source: https://docs.yourhq.ai/reference/configuration

Example of setting GitHub-specific variables for Git remote sync.

```env
GITHUB_TOKEN=your_github_pat
GITHUB_REPO_OWNER=your_org
GITHUB_REPO_NAME=your_repo
```

--------------------------------

### Start websockify (noVNC)

Source: https://docs.yourhq.ai/self-host/gateway-boot

Starts the websockify service for noVNC, which provides remote desktop access. It binds to port 6901 within the container and proxies requests to localhost:5901. Setting NOVNC_BIND to 'off' skips this service.

```bash
websockify --web=/usr/share/novnc 0.0.0.0:6901 localhost:5901
```

--------------------------------

### Caddyfile Example

Source: https://docs.yourhq.ai/self-host/networking

Example Caddyfile configuration for a custom domain, forwarding to localhost.

```caddy
hq.example.com {
    reverse_proxy localhost:3000
}
```

--------------------------------

### Start files-API (conditional)

Source: https://docs.yourhq.ai/self-host/gateway-boot

Starts the files-API if GATEWAY_AUTH_TOKEN is available and FILES_API_BIND is not 'off'. This API serves agent worktrees to the HQ UI file browser with bearer-token authentication.

```bash
FILES_API_BIND=docker FILES_API_PORT=18790 python3 /usr/local/bin/files_api.py
```

--------------------------------

### Command Lifecycle RPCs

Source: https://docs.yourhq.ai/reference/api

Examples of transitioning a command through its lifecycle (start, complete, fail).

```typescript
await supabase.rpc('start_command', { p_command_id: id })

await supabase.rpc('complete_command', {
  p_command_id: id,
  p_exit_code: 0,
  p_stdout: 'Agent provisioned',
  p_stderr: null
})

await supabase.rpc('fail_command', {
  p_command_id: id,
  p_exit_code: 1,
  p_error: 'Template not found'
})
```

--------------------------------

### Preview locally

Source: https://docs.yourhq.ai/development/docs

Navigate to the docs-site directory and start the local development server.

```bash
cd docs-site
mint dev
```

--------------------------------

### Download and inspect the installer script

Source: https://docs.yourhq.ai/self-host/add-gateway

If you prefer to inspect the script before running it, you can download it first and then execute it.

```bash
curl -fsSL https://install.yourhq.ai/gateway -o install-gateway.sh
bash install-gateway.sh
```

--------------------------------

### Task Relations RPC

Source: https://docs.yourhq.ai/reference/database-schema

Example of how to get task relations with joined task metadata.

```sql
get_task_relations(p_task_id)
```

--------------------------------

### Path 2: Clone and Run

Source: https://docs.yourhq.ai/self-host/installation

Steps to clone the repository, set up the environment variables, and run the UI and gateway services using Docker Compose.

```bash
git clone https://github.com/yourhq/yourhq.git
cd yourhq
cp .env.example .env
# edit .env with your Supabase URL + keys, set GATEWAY_AUTH_TOKEN=$(openssl rand -hex 32)
docker compose up -d ui                          # UI only
docker compose --profile gateway up -d            # add gateway services on the same host
```

--------------------------------

### Start Gateway Stack

Source: https://docs.yourhq.ai/development/testing

Brings up the gateway, dispatcher, and runner services and tails their logs. The UI is kept off initially.

```bash
docker compose --profile gateway up -d
docker compose logs -f gateway dispatcher runner embedder file-processor
```

--------------------------------

### Uninstalling YourHQ

Source: https://docs.yourhq.ai/self-host/installation

Commands to uninstall a self-hosted YourHQ installation. This includes stopping and removing Docker containers and volumes, and deleting the installation directory.

```bash
cd ~/.yourhq
docker compose down -v    # DELETES volumes — all agent state gone
cd ..
rm -rf .yourhq
```

--------------------------------

### Configure Network Settings

Source: https://docs.yourhq.ai/troubleshooting/common-issues

Example of modifying .env file for network accessibility across devices on a Tailscale network.

```bash
UI_HOST_PORT=0.0.0.0:3000
FILES_API_HOST_PORT=0.0.0.0:18790
HOST_REACHABLE_URL=http://100.x.y.z    # your Tailscale IP
NETWORKING_MODE=tailscale
```

--------------------------------

### PR Checklist: Booting the Stack

Source: https://docs.yourhq.ai/development/contributing

Command to ensure the development stack boots correctly with both general and development Docker Compose files.

```bash
docker compose -f docker-compose.yml -f docker-compose.dev.yml up
```

--------------------------------

### MagicDNS Example

Source: https://docs.yourhq.ai/self-host/networking

Example of accessing the UI via MagicDNS hostname.

```text
http://yourhq-myserver:3000
```

--------------------------------

### Decryption Errors Example

Source: https://docs.yourhq.ai/guides/secrets-management

An example of a decryption error that might appear in runner logs.

```log
[secrets_sync] Decryption failed: ...
```

--------------------------------

### Build services one at a time

Source: https://docs.yourhq.ai/troubleshooting/common-issues

If swap is added, build services individually to manage resource usage.

```bash
docker compose build ui
docker compose build gateway
docker compose build dispatcher
docker compose build runner
```

--------------------------------

### SupabaseClient usage

Source: https://docs.yourhq.ai/guides/plugins

Example of querying Supabase tables using the SupabaseClient.

```python
budgets = self.ctx.supabase.query("agent_budgets", {
    "agent_id": f"eq.{agent_id}",
    "select": "spent_usd,monthly_limit_usd",
    "limit": "1",
})
```
Tokens:
Raw