> For the complete documentation index, see [llms.txt](https://metalbear.com/mirrord/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://metalbear.com/mirrord/docs/use-cases/local-development.md).

# Remocal Development

Run your code locally while it communicates with real cloud services

mirrord lets developers (or AI agents) run local code in the context of their cloud environment. Your code runs on your machine, but talks to real cloud services - databases, queues, APIs - as if it were deployed in the cluster.

We call this approach "remocal" (remote + local): local execution with remote context.

Want to see it in action? [Watch the demo](https://www.youtube.com/watch?v=ZR7A7cqQcFM).

### The problem

Traditionally, development happens in loops. You write and test code locally, then deploy to staging, where it meets production-like conditions for the first time. Tests fail. You fix, redeploy, repeat.

![The Traditional Dev Loop](https://2838204941-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FghNlSpMkqkYKZCZQsHRt%2Fuploads%2Fgit-blob-6ee3d30d2f11cabe8432f8b6c9dbc9a465769d0b%2Fdevloop.png?alt=media)

This is slow for two reasons:

1. **CI is a bottleneck** - Long test suites, flaky pipelines, and queued builds all add friction.
2. **Staging is fragile** - Deploying unstable code to a shared environment breaks it for everyone.

mirrord removes deployment from the loop entirely. Instead of deploying to test in the cloud, you plug your local process directly into the cloud environment.

### How it works

mirrord runs in two places - in the memory of your local process (`mirrord-layer`) and as a pod in the cluster (`mirrord-agent`).

![mirrord - Basic Architecture](https://2838204941-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FghNlSpMkqkYKZCZQsHRt%2Fuploads%2Fgit-blob-6af7d23d51f055c5c840c576a7ac83e3e31d6329%2Farchitecture.svg?alt=media)

When you start your process with mirrord, it overrides syscalls to:

* **Receive incoming traffic** from the remote pod (mirrored or stolen)
* **Send outgoing traffic** through the remote pod, reaching cluster-internal services
* **Read and write files** on the remote file system
* **Import environment variables** from the remote pod

The agent runs in the network namespace of the target pod and handles the remote side of these operations.

For the full architecture, see the [Architecture reference](/mirrord/docs/reference/architecture.md).

### What makes mirrord different

Other tools use VPNs to connect your machine to the cluster. mirrord works at the process level, overriding individual syscalls. This gives it unique advantages:

* **Fine-grained control** - Choose exactly what happens remotely vs locally. Read some files locally, others remotely. Route some traffic through the cluster, keep other connections local.
* **No root access needed** locally
* **Fast startup** - 15 seconds or less
* **Run multiple sessions** - Each local process can target a different remote pod simultaneously, and [`mirrord up`](/mirrord/docs/using-mirrord/multiple-concurrent-sessions.md) can start and manage several services from a single config file
* **Cluster-agnostic** - Works regardless of network setup (service mesh, VPN, etc.) and scales to 10,000+ pod clusters

[**Get started →**](/mirrord/docs/getting-started/quick-start.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://metalbear.com/mirrord/docs/use-cases/local-development.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.