# Agent skills Skills that teach an agent on your own computer to use agental: the brief, and three that move the repository it is working in into a sandbox, run agents in parallel in forks of it, and set sandboxes up with your keys and git settings. `agental` is the brief. It explains how to create a machine, run commands, keep long work alive, share a port, and what to do with every error. It comes as a short `SKILL.md`, with what every task needs, and a file for each of the rest, such as SSH, the browser, the desktop and webhooks, which your agent opens only when a task calls for it. `agental-move-repo` copies the git repository your agent is working in into a sandbox, with the work that is not committed, and copies it again after the agent changes files. `agental-parallel` forks a prepared sandbox and runs an agent in each fork, each on a branch of its own, and brings the branches back to your repository. `agental-setup` puts the tokens you pick, and your git settings, into a template's secrets. All are written for this deployment, with its sizes, its limits and its addresses. ## Install them One command installs them all for Claude Code, Codex, Cursor and opencode, and for the other agents it finds on your computer. `-g` puts them where every project sees them. Leave it out to install them into the project you are in. ```shell npx skills add https://agental.io -g ``` It reads [the list of skills](https://agental.io/.well-known/agent-skills/index.json) this site publishes, and checks each file it downloads against the sha256 the list gives. `npx skills update` brings them up to date after the brief changes. ## As a Claude Code plugin Claude Code can take both skills as one plugin, from this site. It needs Claude Code 2.1.224 or later. ```shell claude plugin marketplace add https://agental.io/claude-plugins.json claude plugin install agental@agental --scope user ``` Claude Code updates a plugin by itself only when its catalogue's auto-update is on: in `/plugin`, under Marketplaces, turn it on for `agental`. Otherwise `claude plugin update agental@agental` updates it. ## By hand Each agent reads skills from a folder. Claude Code reads `~/.claude/skills`. Codex, Cursor and opencode all read `~/.agents/skills`, and Cursor and opencode read Claude Code's folder as well. Claude Code: ```shell for skill in agental agental-move-repo agental-parallel agental-setup; do zip=$(mktemp) && curl -fsSL https://agental.io/skills/$skill.zip -o "$zip" && mkdir -p ~/.claude/skills/$skill && unzip -oq "$zip" -d ~/.claude/skills/$skill; rm -f "$zip" done ``` Codex, Cursor and opencode: ```shell for skill in agental agental-move-repo agental-parallel agental-setup; do zip=$(mktemp) && curl -fsSL https://agental.io/skills/$skill.zip -o "$zip" && mkdir -p ~/.agents/skills/$skill && unzip -oq "$zip" -d ~/.agents/skills/$skill; rm -f "$zip" done ``` ## Give it the API key The skills read the key from `AGENTAL_API_KEY`. Make one on the console's [API keys](https://console.agental.io/keys) page, and set it where your agent's shell finds it, such as your shell's profile. Do not paste it into a chat with your agent. ```shell export AGENTAL_API_KEY=ag_... ``` ## Tell it when to use a sandbox The skills say how to use a sandbox. These lines say when. Put them in `AGENTS.md` at the top of your project for Codex, Cursor and opencode, or in `CLAUDE.md` for Claude Code. ```markdown ## Sandboxes (agental) Use an agental sandbox for builds, tests, Docker and untrusted code. Never run them on this computer. - How: the `agental` skill. Without it, read https://agental.io/agental-brief.md first. - The API key is in `AGENTAL_API_KEY`. Never print it or write it into a file. - One sandbox per task, named after it. Look with `GET /v1/sandboxes` before you make another. - To bring this repository over, uncommitted work included, use the `agental-move-repo` skill. Use it again after you change files here. - To try several approaches at once, use the `agental-parallel` skill: one agent in each fork of a prepared sandbox. - To give sandboxes the person's tokens or git settings, use the `agental-setup` skill. Never read a token yourself. - When you are done, stop the sandbox (it keeps its disk) or delete it. Sizes and limits: `GET /v1/policy`; prices: `GET /v1/billing/plans`. Never quote them from memory. ``` With them, every build, test and Docker run goes to a sandbox, and nothing your agent builds, downloads or runs touches your computer. ## Moving the repository you are working in Your agent uses `agental-move-repo` when you ask it to move the work to a sandbox, or when the lines above send a build or a test there. It runs a script that comes with the skill, which needs nothing but `bash`, `git`, `tar` and `curl`. - What goes: `.git` whole, with every branch, tag and stash, the commits that are not pushed, and the index; every tracked file as it is on disk; and every untracked file git does not ignore. - What stays: what git ignores; `node_modules`, `dist`, `build`, `target`, `.venv` and other dependencies and build output that git does not ignore; and untracked `.env` files. Keep their values as [secrets of the template](https://agental.io/docs/templates). - Where it lands: `/opt/agental/`. The script checks that `git status`, HEAD, the branch and the stashes are the same on both sides. - Your conversations, when you say so: the Claude Code and Codex conversations had in the repository go along, with its paths made the sandbox's, so that `claude --continue` and `codex resume` there take them up. They may hold what you pasted into them, so your agent asks first. - Its dependencies: the script installs them in the sandbox from the lockfiles the repository has, with `npm ci`, `pnpm`, `bun`, `uv`, `cargo`, `go`, `bundle`, `composer`, Maven or Gradle, and never writes a lockfile. It runs in the background and reports each step, and the agent fixes what fails. - Sent again, the sandbox's copy becomes the same as your computer's, and what was installed in it is kept. - It goes through the files API, in pieces of up to 9 MB, so no SSH port is opened. - Your computer's copy stays as it is. Work done in the sandbox comes back through git. ## Running agents in parallel Your agent uses `agental-parallel` when you want several approaches tried at once, or a large change split among agents. Its script needs `bash`, `git`, `curl`, and `python3` or `node`. - One sandbox is prepared with the repository and its dependencies. Each fork is a copy of its disk, so every agent starts from the same place and none waits for an install. - Each agent, Claude Code, Codex or any command you give, runs in its fork in the background, on a branch of its own. What it leaves uncommitted is committed there when it ends. - Each branch comes back to your repository as a branch of the same name, through a git bundle read with the files API. Nothing is pushed anywhere. - Each fork is billed as a sandbox until it is deleted. The script makes 20 at most at once, and deletes a fork only once its work came back, unless you say otherwise. ## Setting sandboxes up with your keys Your agent uses `agental-setup` when you want your keys or your git settings in your sandboxes, as when an agent there needs its model key. It never reads a value itself: the script sends each from where it is straight to the API. - Tokens it knows by name, found in your environment or from `gh auth token`, such as `GH_TOKEN`, `ANTHROPIC_API_KEY` and `OPENAI_API_KEY`, go only when you pick them. One whose hosts are known is [kept out of the sandbox](https://agental.io/docs/templates#keep-a-variable-out-of-the-sandbox). - Your git settings: who commits, how git pulls and pushes, aliases, and your global ignore file. No credential helper, signing key or include goes. With `GH_TOKEN`, `git push` over HTTPS works. - A token it cannot find, you set yourself in your own terminal, where it is typed unseen. - Its check sends each token to a request of its service that only reads, from inside a sandbox, and says whether it works without bringing it back. ## What the brief says The skill starts with standard skill front matter, so agents that load skills pick it up by themselves. Its description is all an agent reads before it decides to load the rest: ```markdown --- name: agental description: Run commands on a Linux virtual machine of your own, an agental sandbox, over HTTP. Use this when a task needs a real computer that is not the one you are running on. A sandbox can build, test or run code, code you do not trust included; run Docker or install packages; keep a server or a long job running; run a command on a schedule, started for the run when it is stopped; serve a page that someone else can open; be copied, to try several approaches at once; run a browser or a desktop; let a person log in over SSH; be held to the addresses it may reach; have an email address of its own; and report the CPU, memory and disk it uses. Use this too when the person names agental, a sandbox or AGENTAL_API_KEY. metadata: installed-by: agental --- ``` > **Tip:** Every docs page has a "Copy page as Markdown" button too, if you want to give your agent a single topic. [Open the full brief](https://agental.io/agental-brief.md), every part of it in one file. --- Every page of these docs as Markdown: [llms.txt](https://agental.io/llms.txt)