Launch a Private Repository

Before You Begin: A private GitHub repository and a catalog agent you can launch. A launch clones a private repository with a token BoxRouter mints for that one checkout. You never create a personal access token. The repository only has to be linked to your workspace through the GitHub App.

Link the Repository

Follow Connect GitHub and link the repository to your workspace. A private repository can be linked to one workspace at a time; to move it, disconnect GitHub from the old workspace first.

Check Access Before You Launch

The check reads the repository the way a launch would and creates nothing.

import json

from boxrouter import BoxRouter
from boxrouter.models import RepositoryAccess

with BoxRouter() as client:
    access = client.api.launches.check_repository_access("OWNER", "REPO", ref="main")
    if not isinstance(access, RepositoryAccess):
        raise RuntimeError("The access check returned no result")
    print(json.dumps(access.to_dict(), indent=2))

import { BoxRouter } from '@boxrouter/sdk';

const client = new BoxRouter();
try {
  const access = await client.api.launches.checkRepositoryAccess({
    path: { owner: 'OWNER', repo: 'REPO' },
    query: { ref: 'main' },
  });
  console.log(JSON.stringify(access, null, 2));
} finally {
  await client.close();
}

boxrouter api launches check-repository-access OWNER REPO --ref main

A repository the workspace can’t read is a 200 with readable: false and the refusal’s code, message and fix: A readable repository returns visibility, the sha the ref points at, its top-level files and the recipe a launch would use. Omit --ref to check the default branch.

Launch a Pinned Commit

Replace OWNER, REPO and COMMIT_SHA with the repository and its full commit SHA:

from boxrouter import BoxRouter

with BoxRouter() as client:
    with client.sandboxes.launch("codex", repo="OWNER/REPO@COMMIT_SHA") as box:
        print("Sandbox:", box.id)

import { BoxRouter } from '@boxrouter/sdk';

await using client = new BoxRouter();
await using box = await client.sandboxes.launch('codex', { repo: 'OWNER/REPO@COMMIT_SHA' });
console.log('Sandbox:', box.id);

boxrouter launch codex --repo OWNER/REPO@COMMIT_SHA --rm

Launch resolves the ref to a commit before it clones and records that sha on the launch operation. You can use a branch or tag instead; a later launch using a moved branch can select a different commit. --repo owner/repo@ref overrides a catalog agent’s code selection. The ref is required; use @HEAD for the default branch. --rm requests sandbox deletion when you exit. In the SDKs, repo is an option, and leaving the sandbox’s block requests deletion. The SDK returns the sandbox without attaching your keyboard, so the examples print the sandbox ID and leave. The quickstart shows how to confirm it is gone.

What the Clone Token Can Do

BoxRouter mints the token per checkout for that repository alone, with read-only contents and metadata access, and uses it only for the clone. The agent never receives a reusable GitHub credential, so it can’t push.

When Access Fails

Code	HTTP	Meaning
`code_repository_not_found`	404	The repository doesn’t exist or isn’t linked to this workspace.
`code_repository_not_authorized`	403	It is linked, but the GitHub App lost access. Give the App access on GitHub, then retry.
`code_ref_not_found`	404	The branch, tag or commit doesn’t exist.

Each error carries a fix. Launch your own agent lists the full messages.

Next Steps

Supply an Agent's Secrets

Pass a model key without committing it.

Configure a Launch Manifest

Ship setup and the command with your code.

Launch Your Own Agent

A repository, a manifest or an image instead of the catalog.

Launch an Agent

Integrations