---
title: Parallel Agents
description: Run multiple agent sessions in one isolated role instance, or launch separate isolated instances side by side
---
import { Aside } from '@astrojs/starlight/components'

jackin' gives you two different ways to run agents in parallel:

- **Separate instances** — each `jackin load` creates a new isolated container with its own Docker-in-Docker sidecar and agent home. Mounted project files are shared or isolated according to the workspace mount mode.
- **Multiple sessions in one instance** — `jackin hardline --new` starts another agent process inside an already-running instance, sharing the same container state: mounted files, branch, tools, credentials, environment, and Docker-in-Docker sidecar.

Think of a role instance as an isolated collaboration room. The role defines the room: toolchain, shell setup, plugins, supported agent runtimes, credentials, and workspace mounts. The agent sessions are the people working inside it. If the role supports `Claude Code`, `Codex`, `Amp`, `Kimi`, and `OpenCode`, you can start any of those runtimes inside the same running instance.

## Two Parallel Shapes

Use a **fresh instance** when you want a separate container runtime for an agent:

```bash
jackin load the-architect
jackin load the-architect
```

Each command creates a separate container. This is the right shape when you want independent agent homes, sidecars, credentials, tool processes, or task lifecycles. If the agents also need separate branches or worktrees, configure the workspace mount as `worktree` or `clone`, launch a different workspace, or point the load at a different checkout.

Use a **new session in the same instance** when you want agents to share runtime state:

```bash
jackin hardline --new --agent codex
```

That starts another foreground agent session inside the selected running instance. The new session sees the same project files, branch, dependency installs that live in mounted paths, Docker-in-Docker daemon, forwarded credentials, and role tooling as the existing session. It does not inherit the other agent session's conversation context.

## Example: Implement With Claude, Review With Codex

A common workflow is to let one runtime focus on implementation while another runtime focuses on review:

1. Start a role instance for your project.

```bash
jackin load the-architect
```

2. Ask `Claude Code` to implement the change.

3. Open another foreground session inside the same instance.

```bash
jackin hardline --new --agent codex
```

4. Ask `Codex` to review the same branch, run tests, inspect the diff, and leave feedback.

Both agents are working inside the same isolated container. They share the same role tooling, workspace, branch, and runtime environment, but each runtime brings the interaction model and model family it is best at.

This is useful when you want the implementation agent and review agent to reason over the same files without copying state between containers or asking the host to coordinate two checkouts.

## What Shares And What Does Not

Sessions inside the same instance share:

- the workspace files visible to the container
- the current branch or worktree state for mounted repositories
- the role's installed tools and shell setup
- the same Docker-in-Docker sidecar
- the credentials jackin forwarded for every supported runtime in that role
- the container's in-session environment

Separate instances do not share those container runtime surfaces. They may still point at the same host project when a mount uses the default `shared` mode. Use `worktree` or `clone` mount isolation when each container should see its own checkout.

## Choosing The Right Shape

Choose a **new instance** when:

- the agents should work independently
- you want separate agent homes, sidecars, credentials, or task lifecycles
- you have configured `worktree` or `clone` mounts and want each agent to get its own checkout
- one agent might make disruptive container-runtime changes
- you want to compare two approaches side by side

Choose a **new session in the same instance** when:

- one agent is implementing and another is reviewing
- the agents should see the exact same branch and tool state
- you want a second runtime to inspect a long-running task without rebuilding the environment
- you want multiple sessions from the same runtime, such as two `Claude Code` sessions or two `Codex` sessions, in one role instance

## Reconnecting

Closing the terminal does not automatically stop the running instance. Use `jackin hardline` from the project directory to find the matching instance and reconnect or choose an available instance action.

```bash
jackin hardline
```

The console also shows visible instances for the selected workspace or current directory. From the Instances panel, you can recover/reconnect, start another foreground agent session, inspect state, or purge local recovery state when the guarded purge rules allow it.

<Aside type="note">
Today, secondary sessions started with `hardline --new` are foreground sessions. Reconnectable named secondary sessions are tracked under [Console agent session control](/reference/roadmap/console-agent-session-control/). The current stable workflow is: use `jackin hardline` or the console to recover the running instance, then start another foreground session when needed.
</Aside>

## Related Commands

- [`jackin load`](/commands/load/) starts a fresh role instance. Running or stopped instances do not block a fresh launch.
- [`jackin hardline`](/commands/hardline/) reconnects to an existing instance or starts another foreground agent session inside it.
- [`jackin console`](/commands/console/) shows visible instances and common recovery actions from the workspace view.
