OrchaelBridge

Bridge

  • Connect your servers

    Link your bridgectl servers and bring them into one place.

  • See every session

    View AI agent sessions across your servers.

  • Stay in control

    Manage your servers within your organization.

From your terminal to Bridge

Start an agent on your machine, then follow its progress in Bridge. These instructions run locally; opening this guide does not create a session.

  1. Install
  2. Log in
  3. Start the server
  4. Start a session
  5. View in Bridge

  1. Install bridgectl

    Choose your computer’s operating system. Installing on a remote machine? Select that machine’s OS instead.

    The packaged installer supports Ubuntu 24.04 (noble) and 25.04 (plucky), amd64 only. Browser detection cannot identify your distribution or CPU architecture.

    Review the installer before running it with sudo. For other Linux systems, see the upstream source-build instructions.

    Install bridgectl on Linux
    curl -fsSL https://orchael.github.io/bridgectl/install.sh | sudo bash
bridgectl --version

    Install Node.js 24 and configure/authenticate your chosen provider before starting the server. Bridge login does not sign you into Codex or Claude. Ensure Node and the provider are available to the server’s user and shell. See provider setup and authentication.

    Run the remaining commands as your normal user, without sudo, on the same machine. This guide uses a per-user server, not the Ubuntu system-wide service.

  2. Log in and connect this machine

    Log in to Bridge
    bridgectl login 'https://bridge.orchael.com'

    Open the URL printed by the CLI, continue with Google, confirm the device code, and approve the installation in your chosen organization. On a headless machine, open that URL on another device. Wait for authorization to complete in the terminal.

    The organization option is a suggestion; verify the selected organization before approving. Already enrolled? Check bridgectl whoami before proceeding.

    Connecting is opt-in and configures Bridge enrollment/telemetry. Keep credentials on the host; do not paste provider keys or enrollment files into this page.

  3. Start the server

    Start the server in terminal 1
    bridgectl server start

    Keep this terminal open. Start the server after login so it loads the enrollment and connects to Bridge.

    If it was already running before login, finish any active work, then restart that server as the same user. Restarting can interrupt sessions; do not restart a busy host blindly.

  4. Start a new agent session

    In a second terminal on the same machine, change into your repository directory, then run:

    Start a session in terminal 2
    bridgectl session start --provider codex .

    The final . means your current directory. Each invocation creates a new session and attaches your terminal. Press Ctrl-] to detach without stopping it.

  5. View your session in Bridge

    Return to the organization you approved, open Sessions, and locate your provider and installation. Allow the next live refresh, then choose Open session.

    You can follow progress and see when the agent needs an answer or approval. Available interactions depend on the provider and your organization role.

    Sign in and view sessions

    Repeat step 4 for another session. Installation and login are only needed for a new machine or enrollment.

Session not appearing?
Check enrollment, server, and sessions
bridgectl whoami
bridgectl doctor
bridgectl session list

Check the enrolled Bridge URL and organization, the daemon’s connection, and the session list. Confirm that login and the server use the same OS user and state directory. Refresh the Sessions page or clear its filters.

If the enrollment is for another organization, deliberately re-enroll with bridgectl login 'https://bridge.orchael.com' --force and approve the correct organization, then restart the daemon when it is safe. A server started before login must be restarted to load the enrollment.

Login command source · Session command source · Installation documentation