Install AiOrch and run your first session

Before you start

AiOrch runs the orchestrator, agent worktrees and session history on infrastructure you control. The current installer is an interactive Bash script for a Linux host with Docker and the Docker Compose plugin. Run it from an interactive terminal as a non-root operator who can access Docker.

Have a Git repository, a working model-provider account or local inference endpoint, and the repository’s build/test requirements ready. Inference is charged by your chosen providers; it is separate from the AiOrch license.

Install the Docker distribution

Check that the Docker daemon is reachable and Compose is installed:

docker info
docker compose version

Run the public installer in your terminal:

curl -fsSL https://aiorch.ai/install.sh | bash

You can also download and inspect the installer before running it. It prompts for an installation directory, port, host interface, license key and image. The default directory is under your home directory; the default port is 1230 and the published host interface is 127.0.0.1. Leaving the license key empty starts the 14-day trial.

For a local installation using those defaults, open http://localhost:1230. For a remote installation, use your configured private connection. Remote access needs an appropriate TLS-terminating reverse proxy; avoid exposing the raw dashboard port publicly.

Connect a provider and a project

1. Open Settings and set your master password when prompted.
2. Under Providers, configure the provider you intend to use and test its connection. CLI authentication and API keys are different setup paths; see the provider guide.
3. Under Project Directories, make only the intended project subtree available to agents. Verify the project path as seen by the container.
4. For headless CLI agent execution, the current runtime requires explicit ORCH_AGENT_SHELL_AFK opt-in. Before enabling it, verify narrow mounts and acceptable agent permissions: headless agents can execute commands against accessible files. Read the agent boundary guidance.

Available models depend on the provider’s authentication, health and model capabilities. Coding agents require a tool-capable model.

Create and inspect a session

Choose + Session. Enter the task, select the project root and base branch, and choose models for Agent Work, Planning and Review. Planning and review can use different providers from implementation.

Leave Auto-approve plan unchecked for your first session. After planning, inspect the proposed scopes, shared files and dependencies before approving execution. Set a modest parallel-agent limit that fits your machine and provider capacity.

Watch the session’s agent status and review rounds. Confirm which validation actually ran; an approved review is not a substitute for your repository’s tests.

Choose the delivery behavior

Agent-branch integration, remote push and GitHub PR creation are separate options. If you want a pull request, enable the corresponding merge/PR options and configure GitHub access in Settings. Scope that access to the repository you intend to use.

The final PR still needs your team’s review. An independent audit is optional and uses the planning/specification document supplied for that workflow. See review and validation for test configuration and unverified delivery states.

If setup stops

The installer cannot read /dev/tty

Run it from an interactive terminal. Cron and non-interactive SSH invocations do not supply the required prompts.

Docker is installed but unavailable

Check the daemon and your operator account’s Docker access before retrying.

No usable model appears

Test the provider in Settings and confirm authentication, endpoint reachability and tool support.

The project path cannot be found

Check Project Directories and the container-visible path. A path existing on the host does not automatically make it available inside the container.

Validation reports a missing toolchain

Repair the execution environment and rerun the relevant checks. Consult the environment failure policy before treating the result as verified.