Skip to content

Install it on a server ​

CrewHall runs as four containers on one machine: Caddy serving the app and terminating HTTPS, the API, Postgres, and optionally a runner that gives agents their workspaces. One modest VPS is enough to start: 2 vCPU, 4 GB of memory, 40 GB of disk, Debian or Ubuntu LTS.

The images are built and published for you; the server pulls them and never compiles anything.

One command ​

Copy the deployment kit from the repository to the server and run it as root:

bash
scp -r deploy/vps root@your-server:/tmp/crewhall-kit
ssh root@your-server '/tmp/crewhall-kit/provision.sh'

It installs Docker, allows only SSH and the web through the firewall, turns on unattended security updates, puts the kit in /opt/crewhall, and installs two timers: a check for a new image every five minutes, and a nightly backup.

--dry-run prints what it would do without doing it. --every 15min checks less often, --no-firewall leaves your firewall alone.

Point the domain at it ​

One A record, from your domain to the server's IPv4 address (and an AAAA record if it has IPv6). Caddy asks Let's Encrypt for the certificate on first start, which only works once the name resolves, so check with dig +short your-domain before going on.

Start it ​

bash
cd /opt/crewhall
./setup.sh     # generates the secrets into .env, then stops
./setup.sh     # after you have checked that file, starts everything

The first run writes .env with a freshly generated database password, master key and admin password, readable only by root. Check these before the second run:

  • CREWHALL_PUBLIC_URL: https://your-domain
  • CREWHALL_SITE_ADDRESS: your-domain
  • CREWHALL_ADMIN_EMAIL: the first account
  • CREWHALL_IMAGE_TAG: edge to follow main, or a released version, e.g. 0.1.0

Then open your domain and sign in as that address; the password is in .env, and you have to change it immediately.

Back up the master key now

CREWHALL_MASTER_KEY decrypts every provider key and integration token. Copy it into your password manager before you do anything else. A database backup without it restores an installation whose keys cannot be read, and nobody can recover it for you.

Documentation and problem reports ​

The welcome page and the app link to the documentation at https://docs.crewhall.space, and Help → Report a problem in the app emails problem reports to support@crewhall.space, the CrewHall project's address, with the reporter's name and email so they get an answer. To point them at your own, set in .env:

bash
CREWHALL_DOCS_URL=https://docs.your-domain     # "off" removes the links
CREWHALL_SUPPORT_EMAIL=help@your-domain        # "off" removes "Report a problem"

Reports go through your SMTP server. Without one, the dialog opens the person's own mail app instead.

Privacy policy and terms ​

CrewHall publishes a privacy policy at /privacy and terms of service at /terms, linked from the welcome page, the sign-in and sign-up pages and the account page. They describe what CrewHall does with people's data, and name whoever runs the server, which you set in .env:

bash
CREWHALL_OPERATOR_NAME="Your Company SAS"
CREWHALL_OPERATOR_ADDRESS="1 rue de l'Exemple, 75001 Paris, France"
CREWHALL_OPERATOR_COUNTRY=France               # whose law governs the terms

They're a starting point, not legal advice: have them read by someone who knows the law where you operate. To publish your own instead, point the links elsewhere (/privacy and /terms then redirect there), or hide them:

bash
CREWHALL_PRIVACY_URL=https://your-domain/privacy   # "off" removes the link
CREWHALL_TERMS_URL=https://your-domain/terms

Google asks for both links, and your home page, on the consent screen of the app people sign in with (Google Auth Platform → Branding): https://your-domain, https://your-domain/privacy and https://your-domain/terms.

A standard install runs a SearXNG container next to the API: free web search for agents, without a key, through the usual search engines. Only the API reaches it. The first time the API finds it, web search is offered on the platform and on in every space; each space can switch it off or bring its own engine (see Tools). To leave search to each space instead, set CREWHALL_SEARXNG_URL=off in .env and stop the searxng container. A server that installed before it existed needs the new compose.prod.yml and a SEARXNG_SECRET (the deployment kit's README says how).

Model prices ​

The API reads public model prices every hour (LiteLLM's community list, from GitHub, and OpenRouter's model list for OpenRouter providers) and models follow them (Prices). CREWHALL_PRICE_CHECK_SECS sets how often (default 3600; 0 never checks). Set CREWHALL_PRICE_LIST_URL to a copy of the list you host, or to off for a server that shouldn't fetch it. Platform admins can check at once from Platform → Models.

Limits per answer ​

The server doesn't limit how many tokens an answer uses: whoever pays for a model decides. A space's owners and admins can set a limit per answer on each of their models, and you can on the platform's models (Platform → Models); empty means no limit. Your monthly limits on the platform's models still apply (accounts), as do each space's budgets.

What stays is a guard against an agent stuck in a loop: an answer (or a task run) makes at most 50 model calls, its coworkers' included. At that limit, or a model's, the agent answers once more with what it found and says it was cut short. Change the guard in .env:

bash
CREWHALL_MAX_RUN_STEPS=50

CREWHALL_MAX_RUN_TOKENS is no longer read.

Agent workspaces ​

The runner that gives agents a Linux computer holds the Docker socket, which is root on that machine. It is therefore off unless you ask for it:

bash
# in .env (setup.sh writes both secrets on a new install)
CREWHALL_RUNNER_URL=http://runner:9000
CREWHALL_RUNNER_TOKEN=…
CREWHALL_EGRESS_SECRET=…

docker compose -f compose.prod.yml --profile workspaces up -d

The profile starts two services: the runner, and egress, the filter that is computers' only way to the internet (websites over http and https, public addresses only, each space's lists). Computers have no network of their own. Without CREWHALL_EGRESS_SECRET, or with CREWHALL_WORKSPACE_ALLOW_NETWORK=false, they stay offline. Allowlisted sites on a private network (an internal Git server, say) also need CREWHALL_EGRESS_ALLOW_PRIVATE=true on the egress service, on top of the platform's and the space's private-network switches.

Then offer "Computer" in Platform → Tools. See Tools for what it does and what bounds it.

License ​

CrewHall is fair source, under the Functional Source License (FSL-1.1-ALv2, LICENSE.md in the repository). Running it yourself is free and has every feature, for any number of people: for your own company, teaching, research, or setting it up for a client who runs it themselves. What the license doesn't allow is offering CrewHall to others as a competing product or service. Each release becomes available under the Apache License 2.0 two years after it comes out.

For help installing, upgrading or connecting your tools, offline installs or service levels, ask about Enterprise from the pricing page.

CrewHall