Autonomous software development

How to use
OpenHands.

Delegating bounded repository tasks to an agent that can inspect code, edit files, run commands, and test changes inside a controlled execution environment.

Open OpenHands ↗ Official download ↗
What it isopen-source AI software development agent with cloud, terminal, IDE, and local interfaces Workflows2 UpdatedSeptember 2026

OpenHands is a open-source AI software development agent with cloud, terminal, IDE, and local interfaces. Delegating bounded repository tasks to an agent that can inspect code, edit files, run commands, and test changes inside a controlled execution environment. This guide covers the whole path in one place: official access, a first session that produces something reviewable, the checks that make output trustworthy, and the permissions worth limiting before you connect real work.

Troiana principle

AI should make the work easier to inspect. If the workflow removes the source, the owner, or the review step, redesign the workflow.

01

Access & setup

Find, install, and sign in to OpenHands

Get into the official OpenHands experience with the right account and a setup you understand.

  1. 01

    Start at https://openhands.dev/ and confirm the domain before entering account or payment information.

  2. 02

    Availability: OpenHands is available through a managed cloud service, a terminal and IDE workflow, or a self-hosted local GUI with Docker-based sandboxes.

  3. 03

    An OpenHands account for Cloud, or a supported local environment and model credentials for self-hosting; Docker isolation is recommended for local agent execution.

  4. 04

    Sign in with the account you intend to keep using, then review plan, data, notification, and permission settings.

  5. 05

    Run one low-risk test task before connecting sensitive files, repositories, or workspace data.

  • Use official download pages.
  • Review permissions during setup.
  • Keep installers and applications updated.
02

First session

Your first useful OpenHands session

Learn the interaction loop using a small task with a clear outcome.

  1. 01

    Choose Cloud or a Docker-isolated local setup and connect only the repository needed for the task.

  2. 02

    Create a clean branch, inspect repository guidance, and state measurable acceptance criteria.

  3. 03

    Ask OpenHands to investigate and propose a small plan before allowing edits or commands.

  4. 04

    Review the diff, command history, tests, and remaining risks before merging or deploying anything.

  • State the outcome before the background.
  • Provide the real source material.
  • Review the result before expanding the task.
03

Quality control

Check the quality of OpenHands output

Turn generated code into a change you would put your name on in review.

  1. 01

    Restate the intended behaviour and the acceptance criteria before reading a single generated line.

  2. 02

    Read the diff rather than the chat summary; the summary describes intent, the diff describes what actually changed.

  3. 03

    Run the test suite, then write a test that would fail if the change were wrong, and confirm it passes for the right reason.

  4. 04

    Check the edges the model tends to skip: error paths, null and empty cases, concurrency, and migration or rollback behaviour.

  5. 05

    Trace every new dependency, network call, and file write, and confirm each one is genuinely required.

  • Review the diff, never the description of the diff.
  • A passing test suite proves the tests pass, not that the change is correct.
  • Keep changes small enough that a human can actually review them.
04

Privacy & permissions

Use OpenHands safely

Give the tool enough repository access to help, and no more than that.

  1. 01

    Decide what the tool may read and what it may write before connecting a repository.

  2. 02

    Scope tokens and integrations to the narrowest repository, branch, and permission set that still works.

  3. 03

    Keep secrets out of the context window: use environment variables and secret stores, never inline credentials.

  4. 04

    Require review before generated code touches authentication, payments, permissions, migrations, or deletion paths.

  5. 05

    Audit what the integration retained after the session, and revoke access that is no longer needed.

  • OpenHands can execute commands, access the network, use supplied credentials, and modify or delete mounted files. Prefer an isolated sandbox, mount only the intended workspace, keep secrets out of prompts and repositories, enable confirmations for risky actions, constrain network and tool access, review every diff and test result, and never let an agent merge or deploy without the authorization your workflow requires.
  • Follow your organisation's approved-use policy.
  • Never treat fluent output as authorization to act.
05

Core workflows

Step-by-step ways to use OpenHands for the work it does best.

Each workflow below has its own outcome, steps and review checkpoints.

01 WorkflowComplete a repository task safely with OpenHands

Delegate a scoped change in an isolated sandbox while keeping commands, edits, tests, and approval boundaries visible.

 02 WorkflowConfigure a hardened local OpenHands workspace

Set up local agent execution with deliberate filesystem mounts, credentials, network access, and confirmation behavior.

Workflow 01

Complete a repository task safely with OpenHands

Delegate a scoped change in an isolated sandbox while keeping commands, edits, tests, and approval boundaries visible.

Outcome: Produce a verified repository diff without giving the agent unnecessary access to the host, secrets, or release process.

  1. 01

    Create a clean branch and sandbox, mount only the target repository, remove secrets, and record the starting status and test baseline.

  2. 02

    Give OpenHands the issue, acceptance criteria, relevant architecture, prohibited changes, validation commands, and a clear stop condition.

  3. 03

    Ask it to inspect the repository and propose a minimal plan before editing, correcting assumptions and narrowing any unnecessary work.

  4. 04

    Allow bounded actions with confirmations enabled for risky operations, then inspect commands, network use, changed files, and test evidence as it works.

  5. 05

    Run the trusted checks independently, review the complete diff and dependency changes, and merge or deploy only through the normal human-approved process.

What good use looks like

  • Use a disposable or isolated sandbox.
  • Mount only the required workspace.
  • Verify tests outside the agent narrative.

Workflow 02

Configure a hardened local OpenHands workspace

Set up local agent execution with deliberate filesystem mounts, credentials, network access, and confirmation behavior.

Outcome: Create a repeatable local environment that limits the impact of mistakes or hostile repository content.

  1. 01

    Choose the current Docker-based setup, inventory host risks, and define which project files, services, and model provider the agent truly needs.

  2. 02

    Use a dedicated repository checkout and minimal read-write mount, keeping unrelated directories, sockets, credential stores, and production data outside the sandbox.

  3. 03

    Provide short-lived least-privilege credentials through approved configuration and restrict outbound access or tools where your environment permits.

  4. 04

    Enable action confirmations and security analysis, then test harmless, destructive, unknown-risk, network, and secret-access scenarios before real work.

  5. 05

    Document setup, image and dependency versions, logs, cleanup, credential rotation, and an incident procedure; review the boundary after every upgrade.

What good use looks like

  • Prefer Docker isolation to direct host execution.
  • Use short-lived least-privilege credentials.
  • Test rejection and cleanup paths.
06

Official references

Check the current product documentation.

Features, plan limits, availability, and data controls change. These official pages are the starting points used for this guide.

Explore the Troiana AI Hub →