# Starplex documentation > Install Starplex and connect your coding agents to its shared record. For agents: read Install, Sign in and Connect in order. Explain each command before running it. Ask the person to complete browser sign-in. Finish by reading their project through your own Starplex tools. # Set up Starplex with your agent

Give your coding agent the instruction below. Stay with it for browser sign-in and the choice of organizations.

## Give this to your agent ```text Help me set up Starplex for this repository. Read https://docs.starplex.dev/llms.txt, then follow Install, Sign in and Connect in order. Explain each command before running it. Let me finish the browser sign-in and choose my organizations. Finish by reading my project through your own Starplex tools and confirming its name and connected repositories. ``` You need an invitation to a Starplex organization before you can sign in. ## Read the docs as an agent [starplex.dev](https://starplex.dev) is the public introduction. The documentation index is [/llms.txt](/llms.txt), and [/llms-full.txt](/llms-full.txt) contains all the pages. Each page has a Markdown copy. Use [/index.md](/index.md) for Overview, [/install.md](/install.md), [/sign-in.md](/sign-in.md), [/connect.md](/connect.md), and [/agents.md](/agents.md). The page's **View as Markdown** link opens its copy. ## Know when setup is done Read the person's project through your own Starplex tools from this repository's agent session. Confirm its name and connected repositories with them. A command run in a terminal doesn't prove your agent has connected. --- # Connect a repository

Connect your project folder, restart your agent when needed, then ask it to read your Starplex project.

## Before you start [Install the CLI](/install), [sign in](/sign-in), and open a terminal in the repository you want to use. You'll need a Starplex project connected to that repository, and Claude Code, Codex or OpenCode installed. ## Connect

  1. Write the relay entries

    ```sh frame="terminal" starplex setup-mcp ```

    Run this in the repository every time you connect a machine, including when relay entries are already committed. It writes entries for Claude Code, Codex and OpenCode, checks your sign-in, and reports what still needs attention.

    Read the result for each app. Follow any instructions to remove old user-level entries or resolve conflicting settings.

    Setup reports a conflict

    Read the named file and conflicting entry before changing it. Preserve unrelated settings. If you need help, share the conflict report with your agent.

  2. Restart your coding agent when told

    Use a fresh window or chat after changing the relay configuration. Keep the agent in this repository so it reads this folder's configuration.

    The agent can see its Starplex tools.

  3. Ask your agent to read the project

    Give it your project slug and ask it to read that project through its own Starplex tools. For example:

    ```text Read my Starplex project using your Starplex tools and tell me its name and connected repositories. Ask me for the project slug if you need it. ```

    You're connected when the agent reads the right project through its own tools. A successful terminal command alone isn't this check.

    The agent can't see the tools

    Run setup again in the same folder and read the per-app report. Follow its restart instructions, then try the project read in a fresh chat.

## Verify the connection Run `starplex setup-mcp` again after the project read. Its per-app report distinguishes a relay that has started from an agent that has read a project of this folder. Check the app you actually used. --- # A software factory that runs on your own coding agents.

Starplex is an issue tracker that also does the work. Your own coding agents, such as Claude Code, Codex or OpenCode, pick up its tickets and work through many at once, on your own machines. Riskier work gets more checks, and you decide what merges.

Install the CLI →Set up with your agent
## Get started in three steps

Starplex is invite-only for now. You'll need an invitation to an organization before you can sign in.

  1. Install

    One command puts the starplex CLI on your machine.

  2. Sign in

    Choose the organizations your sign-in reaches.

  3. Connect a repository

    Give your agent Starplex's tools in a project folder.

## What you're installing

Reading this as an agent?

Every page has a Markdown copy. Use the View as Markdown link. /llms.txt lists them all, with instructions for setting up Starplex for the person you're working with.

--- # Install the Starplex CLI

The Starplex CLI connects your coding agents to Starplex. One command installs it for your user account. It doesn't need administrator access.

## Before you start ## Install

  1. Run the installer

    Paste this into your terminal. It downloads the CLI from Starplex and puts the starplex command in ~/.local/bin.

    ```sh frame="terminal" curl -fsSL https://app.starplex.dev/install.sh | sh ```
    It's done when the last line reads Starplex CLI installation finished, followed by the build and where it put the command.
    It says Node 26 or later is required

    The installer checks your Node version first and changes nothing if it's too old. Install Node 26 or later with your version manager, open a new terminal, and run the installer again.

  2. Check the command is on your PATH

    Check that your shell can find the command:

    ```sh frame="terminal" starplex --version ```
    You'll see one line naming the CLI's version and the build that was installed.
    command not found: starplex

    The installer prints this fix when ~/.local/bin isn't on your PATH. Add this line to your shell profile, such as ~/.zshrc, then open a new terminal:

    ```sh frame="terminal" title="~/.zshrc" export PATH="$HOME/.local/bin:$PATH" ```

Updates are automatic. The CLI keeps itself on the build the Starplex server runs, so you don't need to run the installer again.

--- # Sign in to Starplex

Sign in on your machine so your coding agents can reach Starplex. You'll choose which organizations that sign-in covers.

## Before you start [Install the CLI](/install) and accept an invitation to a Starplex organization. Use the account that received the invitation. ## Sign in

  1. Start sign-in from your terminal

    ```sh frame="terminal" starplex login --server https://app.starplex.dev ```

    The CLI prints a sign-in address and tries to open your browser. If it doesn't open, follow the printed address yourself.

    On a remote machine, such as one reached over SSH, the browser can't open by itself; after you approve access, it ends on a page that fails to load, so copy that page's full address and paste it at the terminal's prompt. On your own machine, the CLI finishes by itself.

    Keep this terminal open while you finish in the browser.

  2. Choose your organizations in the browser

    Sign in, then approve access to the organizations you want to use. Your consent covers each whole organization. Choosing a project later does not narrow that access.

    Return to the terminal. A successful result reports your sign-in and organization coverage.

    Your organization isn't listed

    Check that you accepted its invitation and signed in with the invited account. Ask the person who invited you if you still can't see it.

## Check your sign-in ```sh frame="terminal" starplex auth-check ``` A successful check reports a state of `locally_ready` for the selected connection. It reads only your machine, so the server's acceptance is reported as unknown; the agent's project read on the Connect page proves the server side. If it reports that you aren't signed in, run the login command again and finish the browser step. Your credentials stay on your machine. Connecting a repository writes relay configuration, not credentials, into the project.