Agent Devenv

Agent Devenv is largely documentation, and proposes the infrastructure and workflow for your AI agent(s) to remotely develop software in a sandboxed*, secure*, and safe* environment.

* Well… something closer to it at least! **insert warranty disclaimer**

You'll adopt a stack of reputable, vendor-agnostic, and Open Source software to drive your AI coding agent using your autonomous AI agent. The repository is catered to the following assumptions:

• You run an autonomous agent on a server, like Hermes or OpenClaw. (Optional, you can disable and skip the SSH steps.)
• You run a coding agent on your computer, like OpenCode or Cline. (Optional, your autonomous agent could fulfil this role itself.)
• However, if neither are true, you're probably in the wrong place.

Safeguards

What	Caveats
Agent logs in as a non-sudo user.	If you choose to setup rootful Docker, the agent can bypass this by mounting the root of the VM in a rootful container.
Isolated file system with no mounts by default.	If you choose to mount directories with writable: true, it effectively grants the agent the capabilities to write to the host file system.
Can not access private networks by default.	When this is done in the VM only, other privilege escalations like rootful Docker could bypass this by simply turning off the firewall.

Prerequisites

Software	Reason
Lima	To provision a virtual machine.
Ansible	To provision the development environment to a virtual machine.
Make	To run lifecycle tasks.

Getting Started

1. Provision the VM

Open agent-devenv.yml in the root of this repository, and configure mounts your agent will need to work. For example:

agent-devenv.yml

 mounts:
+  - location: "~/Projects"
+    mountPoint: "{{.Param.Home}}/Projects"
+    writable: true
+  - location: "~/.config/opencode"
+    mountPoint: "{{.Param.Home}}/.config/opencode"
+    writable: false
+  - location: "~/.local/share/opencode"
+    mountPoint: "{{.Param.Home}}/.local/share/opencode"
+    writable: true
+  - location: "~/.local/state/opencode"
+    mountPoint: "{{.Param.Home}}/.local/state/opencode"
+    writable: true

Now run some Make recipes! You can inspect Makefile to learn what it's doing:

# This will:
# - Create an SSH config for remote access.
# - Provision the VM if it doesn't already exist.
# - Start the VM so that it's ready to use.
make start

# (Optional) You can shell into VM yourself.
make shell

📝 Read more about exposing files to the VM.

2. Onboard your Autonomous Agent

In .agent-devenv, you'll find an SSH keypair and SSH config. These files need to be handed to your autonomous agent so it can remote into the VM.

File	Purpose
.agent-devenv/ssh-key	Agent's SSH private key for authentication.
.agent-devenv/ssh.config	SSH config with host information and connection details. The agent will use ssh -F /path/to/ssh.config to connect to the virtual machine.

On your server, create a directory to mount to the autonomous agent container, then copy the files over. For example:

Filesystem

├── docker-compose.yml
└── secrets
    ├── ssh.config
    └── ssh-key

docker-compose.yml

 services:
   ai-agent:
     …
     volumes:
+      - "./secrets:/secrets:ro"

3. Teach your Autonomous Agent

One way or another, explain to your agent how to use these credentials. A simple skill works:

…/remote-software-engineer/SKILL.md

---
name: "remote-software-engineer"
description: "…"
---

There is a provisioned <abbr title="Virtual Machine">VM</abbr> for you to access via SSH to plan, develop, test, and assist in software development.

Connect using the provided SSH config, e.g.:

- `ssh -F /secrets/ssh.config agent-devenv …`
- `scp -F /secrets/ssh.config agent-devenv …`

Will your VM have a dedicated coding agent installed like OpenCode or Cline?

Be sure to tell your autonomous agent what relationship it should have with your coding agent. For example:

…/remote-software-engineer/SKILL.md

 …

+ The VM has OpenCode installed, an AI coding agent. The coding agent will have information relevant to the client, projects, and tasks for this session. You are welcome to invoke tools and perform work yourself, however, your primary role is to consult with and drive the coding agent in the VM.

4. Provision the Development Environment

Your agent should now be able to SSH into the VM and read your projects. However, it doesn't have any development tools installed.

This step is your job—there is no one-size-fits-all image. It's recommended to define your provisioning script as an Ansible playbook so that it's easy to amend and reapply.

You can copy the generic playbook and use our predefined roles in ansible/roles as a starting point:

cp ansible/playbooks/generic.yml ansible/playbooks/custom.yml

📝 Not sure how to use Ansible roles?

Once you're ready, to provision the development environment to the VM:

PLAYBOOK=custom make provision

And with that, you (and your agent) are all set up! 🎉