hangar create

Creates a Hangar and starts it. The agents are installed on its first start, each in a window of its own, and without --agent you get claude-code and codex. --terminal-only installs none, and the Hangar opens on a plain shell.

Variables and variable groups are set here as well. Each agent signs in from its own window with your account, and an agent that reads an API key from a variable can be given one here with --env instead. env set --hangar and env group assign --hangar change them later, and a change applies the next time the Hangar starts.

--repo and --branch pick a GitHub repository to clone into the home directory under its own name, once, on the first start. A private one is read through the GitHub installation you granted, as for app create, and --public-repo reads a public one without it; repos lists what you can pick. To push from the Hangar, sign in to GitHub in its terminal, as Push from a Hangar describes. --repo needs outplane v0.2.15 or newer.

The command returns while the Hangar is still starting. Poll hangar get until status is ready, then connect. The name is permanent, follows the application rule of letters and numbers, 5 to 45 characters, and is shared with applications.

Usage

outplane hangar create <NAME> [flags]

Arguments

Flags

The global flags apply as well.

Output

Examples

With the agents the console preselects

outplane hangar create myhangar

With one agent and no idle timeout

outplane hangar create myhangar --agent codex --idle-timeout never

With a repository cloned in on its first start

outplane hangar create myhangar --repo acme/web --branch main

With a variable and a shared group

outplane hangar create myhangar --env LOG_LEVEL=debug --env-group shared

Create one and read its id and state in a pipeline

outplane hangar create myhangar --json --fields id,status

{
  "id": "3f2b1c4e-0000-0000-0000-000000000000",
  "status": "deploying"
}

Check the request without sending it

outplane hangar create myhangar --terminal-only --dry-run --json

{
  "agents": [],
  "changed": false,
  "id": null,
  "idleTimeoutMinutes": 30,
  "name": "myhangar"
}

What to Know

• Creating starts the Hangar. The command returns as soon as it exists, with status deploying; outplane hangar get <name> reports when it is ready, and outplane hangar connect is refused with hangar.not_running until then.
• A Hangar that is created but cannot start still exits 0, with status failed. Its name stays taken until it is deleted.
• The name is stored in lower case, and the name as typed becomes the display name. name in the result is the one other commands take.
• Applications and Hangars share one set of names. A name an application already has is refused with exit 6 and hangar.name_taken, although hangar list does not show it.
• A team has a fixed maximum number of Hangars. Reaching it is exit 7 with hangar.limit_reached; retrying never helps, and deleting one makes room.
• Without --agent, claude-code and codex are installed, as in the console. --terminal-only installs none.
• Without --idle-timeout, the Hangar pauses after 30 minutes idle. With an idle timeout, the platform checks every 5 minutes and pauses a Hangar whose terminal has had no output in any window and no key from anyone connected for that long, so 30m pauses it 30 to 35 minutes after the last activity. A paused Hangar keeps its disk, its ports and its variables, and outplane hangar resume starts it again. outplane hangar update --idle-timeout changes it later.
• The size and the disk are set by the platform, not by a flag. Under --dry-run they are null, as are id and status.
• Variable values are never echoed back; envCount reports how many were set. A variable set with --env wins over a group's, and between groups the one given later wins. A group used only at build reaches nothing here, because a Hangar never builds. outplane env set --hangar and outplane env group assign --hangar change them afterwards, and a change applies the next time the Hangar starts.
• --env-group takes a name or an id. Each one is resolved with a request of its own before anything is sent, under --dry-run as well.
• --repo is cloned into ~/<name> once, on the first start, at --branch, which it requires. A clone that fails is not tried again: the Hangar's terminal says why and gives the command to clone it by hand. The repository cannot be changed afterwards. --branch or --public-repo without --repo is hangar.repository_required.
• A private repository is read through the GitHub installation of the user whose token this is, as for app create; --public-repo skips that. hangar.repository_unavailable means the platform cannot see it, and the error points at outplane repos and the page that grants access.
• Out Plane only clones. To push, and to fetch a private repository later, sign in to GitHub in the Hangar's terminal with gh auth login, or with a token for that repository.
• Everything the server would refuse is checked first, so an error names the field. The exceptions are the name being taken, the team's limit, and whether the repository and its branch can be read, which only the server knows.

Errors

Beyond 0 for success, this command exits with:

The code on the error object is one of hangar.name_invalid, hangar.name_reserved, hangar.name_taken, hangar.agent_invalid, hangar.agent_duplicate, hangar.agent_conflict, hangar.idle_timeout_invalid, hangar.env_group_duplicate, hangar.repository_invalid, hangar.branch_required, hangar.repository_required, hangar.repository_unavailable, hangar.limit_reached, envgroup.not_found, envgroup.ambiguous, env.reserved_key, env.reserved_prefix, usage.missing_argument, usage.empty_argument, usage.bad_assignment, usage.duplicate_key, context.no_team. Branch on that, or on the exit status. The message is prose and changes.

Related