The fastest path is the one-line installer in Quick Start. It runs the steps below for you and prints onboarding hints. To do it by hand:

# 1. Create the project research-stack template (no idea2paper code in here —
#    each new project clones this env, so it must stay clean).
conda env create -f environment.yml         # Linux (creates "ark-base")
# OR for macOS:
conda env create -f environment-macos.yml   # macOS (creates "ark-base")

# 2. Install idea2paper itself into a SEPARATE env (not ark-base).
conda create -n ark python=3.11 -y
conda activate ark
pip install -e .                    # Core
pip install -e ".[research]"       # + Gemini Deep Research & Nano Banana
pip install -e ".[webapp]"         # + dashboard / systemd service support

# 3. Install the OpenHands CLI (the agent runtime). It is a standalone `uv`
#    tool with its OWN bundled Python 3.12 — NOT a pip dependency — and must be
#    on PATH for the orchestrator subprocess to find it.
pip install uv && uv tool install --python 3.12 openhands

# 4. Verify (checks the openhands runtime is on PATH, keys are present, etc.)
ark doctor

Each iteration of the Review phase runs 5 steps:

The loop repeats until the score reaches the acceptance threshold — or you intervene via Telegram.

Each project runs in its own per-project conda environment, cloned from a base env at project creation. This ensures full multi-tenant isolation:

• Sandboxed Python — per-project .env/ directory with its own packages
• Isolated HOME — each orchestrator runs with HOME set to the project directory
• No cross-contamination — PYTHONNOUSERSITE=1 prevents leaking user-site packages
• Automatic provisioning — ark run and the Web Portal detect and use the project conda env; the pipeline bootstraps it if missing

# The conda env is created automatically on first run.
# ark run will detect and use it:
ark run myproject
#   Conda env: /path/to/projects/myproject/.env

idea2paper ships with builtin skills — modular instruction sets that agents load at runtime to enforce best practices:

Skills live in skills/builtin/ and are auto-installed during pipeline bootstrap. Domain skills (e.g., HPC) live in skills/library/ and are pulled in by the Researcher when relevant.

python -m ark.orchestrator --project myproject --mode paper --max-iterations 20
python -m ark.orchestrator --project myproject --mode dev

Running with Docker Compose

# Start the web portal (builds the image automatically for amd64)
docker compose -f docker/docker-compose.yml up --build -d

The web portal will be accessible at http://localhost:9527. All databases, configurations, and project data are persisted in a Docker named volume (ark_data).

docker compose -f docker/docker-compose.yml logs -f webapp

Configuration

cp .ark/webapp.env.example .ark/webapp.env
# Edit .ark/webapp.env with your credentials

Then uncomment the environment volume mapping in docker/docker-compose.yml under the webapp service:

      - ../.ark/webapp.env:/data/.ark/webapp.env:ro

Running Individual Jobs

Uncomment the job service in docker/docker-compose.yml, then run:

docker compose -f docker/docker-compose.yml run --rm job \
  --project myproject \
  --project-dir /data/projects/<user-id>/myproject \
  --mode research \
  --iterations 10

Pass required API keys (e.g., ANTHROPIC_API_KEY, GEMINI_API_KEY) as environment variables.

Running Standalone Containers

# Build images (force amd64)
docker build --platform linux/amd64 -f docker/Dockerfile.webapp -t ark-webapp .
docker build --platform linux/amd64 -f docker/Dockerfile.job -t ark-job .

# Run the Web Portal
docker run -d --name ark-webapp \
  --platform linux/amd64 \
  -p 9527:9527 \
  -v ark_data:/data \
  ark-webapp

# Run a Research Job
docker run --rm -it \
  --platform linux/amd64 \
  -v ark_data:/data \
  -e ANTHROPIC_API_KEY="sk-ant-..." \
  ark-job \
  --project myproject \
  --project-dir /data/projects/myproject \
  --mode research

Pushing to GCP

# Push to Artifact Registry (recommended)
./docker/push-gcp.sh --project [PROJECT_ID] --region [REGION] --repo [REPO] --build

# Push to Legacy Container Registry (gcr.io)
./docker/push-gcp.sh --project [PROJECT_ID] --legacy --build

The --build flag automatically builds the images for linux/amd64 even when running on macOS.

idea2paper uses a three-tier configuration model for cloud compute:

1. System Defaults: Set in webapp.env (e.g., CLOUD_REGION, CLOUD_NETWORK).
2. Global User Defaults: Set in the Settings panel (⚙️). These apply to all your projects.
3. Project Overrides: Set during project creation or restart. These have the highest priority.

This hierarchy lets you define standard machine types and VPC settings once, while easily swapping to a powerful GPU instance for a specific experiment.

Once cloud compute is configured, launch a project through the dashboard:

1. Click New Project from the dashboard home.
2. Fill in the research goal, target venue, and any additional instructions.
3. Click Submit — the webapp generates a config.yaml, provisions the Orchestrator VM, syncs your project, and starts the run.

The generated config.yaml is stored at:

~/.ark/data/projects/<user_id>/<project_id>/config.yaml

You can inspect or hand-edit this file at any time (e.g., to tune instance type or add setup_commands). Changes take effect on the next run or restart.

1. Create a Service Account

export PROJECT_ID=your-gcp-project-id

# Create a service account for idea2paper
gcloud iam service-accounts create ark-runner \
  --display-name="ARK Research Runner"

# Grant required roles (Compute Admin + Service Account User)
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:ark-runner@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/compute.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:ark-runner@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountUser"

# Download the JSON key
gcloud iam service-accounts keys create ~/ark-gcp-key.json \
  --iam-account=ark-runner@${PROJECT_ID}.iam.gserviceaccount.com

2. Enable Required APIs

gcloud services enable compute.googleapis.com --project=$PROJECT_ID

3. Build the Machine Image

idea2paper uses a pre-baked Machine Image containing all system dependencies (Conda, LaTeX, Node.js) for fast boot times. Build it once:

./scripts/build_ark_gcp_image.sh [GCP_PROJECT_ID] [ZONE]

This script spins up a temporary VM, installs TeX Live, Miniforge, Node.js, and the ark-base environment, then saves a Machine Image named ark-job-v1-[timestamp] tagged with the ark-job family.

4. Configure in Dashboard

Paste the contents of ~/ark-gcp-key.json into the GCP Service Account JSON field and set your GCP Project ID in the Settings panel.

5. Finding GCP Parameters (Optional)

# List available zones
gcloud compute zones list

# List available machine types in a specific zone
gcloud compute machine-types list --zones=us-central1-a

# List networks and subnets
gcloud compute networks list
gcloud compute networks subnets list --regions=us-central1

Alternatively, use the Google Cloud Console:

• Zones/Machine Types: Compute Engine → VM Instances → Create Instance
• Networks: VPC Network → VPC Networks
• Images: Compute Engine → Images

6. config.yaml Reference (advanced / CLI only)

The webapp generates this automatically from your Settings. For manual or CLI-driven projects, see config.example.yaml for the full template. The model + keys (all agents run through OpenHands → LiteLLM):

model: anthropic/claude-sonnet-4-6     # agents run this — any LiteLLM model
                                       # (gemini/… , openai/… , deepseek/… , …)
bot_model: anthropic/claude-haiku-4-5  # cheap model for light helpers (titles, summaries)
anthropic_api_key: "sk-ant-..."        # fill the provider(s) you use — the model
openai_api_key:    "sk-..."            #   prefix picks which key is used
gemini_api_key:    "..."               # gemini key also powers Deep Research (optional)

Compute uses two backends (orchestrator VM + experiment VM):

# Orchestrator VM: runs Researcher, Planner, Writer, LaTeX (no GPU needed)
orchestrator_compute_backend:
  type: cloud
  provider: gcp
  region: us-central1-a
  instance_type: n1-standard-2
  image_family: ark-job              # Pre-baked idea2paper image

# Experiment VM: runs GPU-intensive workloads
experiment_compute_backend:
  type: cloud
  provider: gcp
  region: us-central1-a
  instance_type: g2-standard-4
  accelerator_type: nvidia-l4
  accelerator_count: 1
  # Optional: post-boot setup
  setup_commands:
    - conda activate base && pip install -r requirements.txt

To run experiments on the Orchestrator VM instead of a separate instance, set experiment_compute_backend.type: local.

1. Create an IAM User

# Create an IAM user for idea2paper
aws iam create-user --user-name ark-runner

# Attach policy (EC2 full access is sufficient)
aws iam attach-user-policy \
  --user-name ark-runner \
  --policy-arn arn:aws:iam::aws:policy/AmazonEC2FullAccess

# Create access keys
aws iam create-access-key --user-name ark-runner
# Note the AccessKeyId and SecretAccessKey from the output

2. Create an SSH Key Pair

# Create a key pair and save locally
aws ec2 create-key-pair \
  --key-name ark-key \
  --query 'KeyMaterial' \
  --output text > ~/.ssh/ark-key.pem
chmod 600 ~/.ssh/ark-key.pem

3. Configure in Dashboard

Enter your AWS Access Key ID, AWS Secret Access Key, and AWS Region (e.g., us-east-1) in the Settings panel.

4. config.yaml Reference (advanced / CLI only)

experiment_compute_backend:
  type: cloud
  provider: aws
  region: us-east-1
  instance_type: g4dn.xlarge        # 1x T4 GPU, 4 vCPUs, 16 GB RAM
  image_id: ami-0c7c51e8edb7b66d3   # Deep Learning AMI (Ubuntu 22.04)
  ssh_key_name: ark-key              # Key pair name in AWS Console
  ssh_key_path: ~/.ssh/ark-key.pem
  ssh_user: ubuntu
  security_group: sg-xxxxxxxx        # Must allow inbound SSH (port 22)
  setup_commands:
    - conda activate pytorch && pip install -r requirements.txt

1. Create a Service Principal

# Login
az login

# Create a service principal with Contributor role
az ad sp create-for-rbac \
  --name "ark-runner" \
  --role Contributor \
  --scopes /subscriptions/YOUR_SUBSCRIPTION_ID
# Note: appId (Client ID), password (Client Secret), and tenant (Tenant ID)

2. Register the SSH Public Key

# Generate an SSH key if you don't have one
ssh-keygen -t rsa -b 4096 -f ~/.ssh/ark-azure-key

# The public key (~/.ssh/ark-azure-key.pub) will be used automatically

3. Configure in Dashboard

Enter your Azure Client ID, Azure Client Secret, Azure Tenant ID, and Azure Subscription ID in the Settings panel.

4. config.yaml Reference (advanced / CLI only)

experiment_compute_backend:
  type: cloud
  provider: azure
  region: eastus                     # Azure location
  instance_type: Standard_NC6s_v3    # 1x V100 GPU, 6 vCPUs, 112 GB RAM
  image_id: UbuntuLTS                # OS image alias
  ssh_key_path: ~/.ssh/ark-azure-key
  ssh_user: azureuser
  resource_group: ark-resources      # Will be created if it doesn't exist
  setup_commands:
    - pip install -r requirements.txt

• Log Streaming — the Orchestrator VM maintains a logs/latest.log symlink; the webapp polls it periodically to show live progress.
• State Sync — every 60 seconds, the launcher pulls the auto_research/ state directory back from the VM to update the Dashboard UI.
• Re-attachment — if you restart your local webapp, idea2paper detects the existing orchestrator_instance.yaml, probes the remote VM via SSH, and re-attaches to the running process without re-provisioning.

ark setup-bot    # one-time: paste BotFather token, auto-detect chat ID

What you get:

• Rich notifications — formatted score changes, phase transitions, agent activity, and errors
• Send instructions — steer the current iteration in real time
• Request PDFs — latest compiled paper sent to chat
• Human intervention — agents escalate decisions to you before irreversible actions
• HPC-friendly — handles self-signed SSL certificates on enterprise/HPC networks