Skip to content
Skills Library
DevOps & cloud · Automation

margin-setup

/margin-setup

Install Margin and set up a private hub (docs where many people and many AI agents write together) on the user's own machine, their VPS, or their Cloudflare account, then connect Codex / Claude Code agents to it. Use when the user wants to install, host, deploy, invite people to, connect agents to, or remove Margin.

Repository
margin ↗
Licence
MIT
Last repository change
02.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
0
HTML comments
0
URLs in SKILL.md
4
Deprecation

No signals detected. Repository changed on 02.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Install Margin and set up a private hub (docs where many people and many AI agents write together) on the user's own machine, their VPS, or their Cloudflare account, then connect Codex / Claude Code agents to it. Use when the user wants to install, host, deploy, invite people to, connect agents to, or remove Margin.

Original author description

Install Margin and set up a private hub (docs where many people and many AI agents write together) on the user's own machine, their VPS, or their Cloudflare account, then connect Codex / Claude Code agents to it. Use when the user wants to install, host, deploy, invite people to, connect agents to, or remove Margin.

How it works

  1. 1. Check Node.js
  2. 2. Install the CLI
  3. 3. Ask one question: where should the hub live?
  4. 4. Add the user's agents
  5. 5. Hand over
  6. Removing Margin
  7. Safety rules
Original SKILL.md headings · 102 lines, 833 words
SKILL.md preview
---
name: margin-setup
description: Install Margin and set up a private hub (docs where many people and many AI agents write together) on the user's own machine, their VPS, or their Cloudflare account, then connect Codex / Claude Code agents to it. Use when the user wants to install, host, deploy, invite people to, connect agents to, or remove Margin.
---

# Set up Margin

Margin is an open-source toolkit, not a service: a **hub** (docs, comment threads, agent inboxes)
runs on something the user owns, and a **computer** process on their machine hosts their agents
(Codex, Claude Code, the Claude API) and wakes them when someone @mentions them in a doc.
Agents never write into docs directly: they propose edits, and people approve them.

Work through the steps in order. Ask the user only where a step says to ask. Tell them in one line
what you're doing as you go.

## 1. Check Node.js

```bash
node -v    # needs v20 or newer
```
If it's missing or older, stop and tell the user how to get it (https://nodejs.org, `brew install node`,
or `nvm install 22`). Don't install system software without their OK.

## 2. Install the CLI

```bash
npm install -g https://github.com/LLTOMZHOU/margin/releases/latest/download/margin-hub.tgz
margin help
```
If `npm install -g` fails with `EACCES`, install into the user's home instead and use the full path:
```bash
npm install -g --prefix ~/.local https://github.com/LLTOMZHOU/margin/releases/latest/download/margin-hub.tgz
~/.local/bin/margin help        # suggest adding ~/.local/bin to PATH
```
Then keep these instructions with the user's agents for next time (copies `margin-setup` and
`margin-agent` into `~/.claude/skills` and `~/.agents/skills`):
```bash
margin skills install
```

## 3. Ask one question: where should the hub live?

| Option | Good for | Cost | What the user does |
| --- | --- | --- | --- |
| **This machine** (default) | trying it, solo use, a team on one network | free | nothing |
| **Their Cloudflare account** | a team, always on, nothing to maintain | free tier is enough for small teams | signs in once with `npx wrangler login` |
| **Their VPS** | full control, own domain | the VPS | gives you a host you can `ssh` into |

If they don't mind, use **this machine** now; moving to Cloudflare later is one command.
For this machine, start a clean hub named for them (`--seed welcome --space "…"`) unless they only
want to look around, in which case the sample doc with demo agents (the default) is nicer.
Never host it on a service run by someone else: the point is that it's theirs.

Then follow the guide for their choice:
- This machine → [reference/local.md](reference/local.md)
- Cloudflare → [reference/cloudflare.md](reference/cloudflare.md)
- VPS → [reference/vps.md](reference/vps.md)

## 4. Add the user's agents

See which agent CLIs this machine has:
```bash
command -v codex; command -v claude
```
For each one that's installed, offer to add it (one line each, not a questionnaire):
```bash
margin agents add Codex  --runtime codex       --about "Careful line editor. Proposes small edits."
margin agents add Claude --runtime claude-code --about "Research partner. Checks claims, drafts sections."
margin agents list
```
They run on this machine through the computer started with the hub, signed in as the user already is.
If `agents add` warns that a CLI isn't signed in, tell the user the exact login command it printed;
`agents list` shows such an agent offline with the reason. "Online" means a computer is hosting it;
the real test is mentioning it in a doc and seeing it reply.
Every new hub also has four built-in demo agents (`@Editor`, `@Fact-Checker`, `@Skeptic`, `@Scribe`:
rule-based, no model), so there's always something to try even without Codex or Claude Code.
Details, runtimes and safety settings: [reference/agents.md](reference/agents.md).

## 5. Hand over

Tell the user, in this order:
1. the link to open (for a hub other people can reach, the invite link `…/?key=…`, and that anyone
   with it can get in, so share it only with people they trust);
2. "Select any sentence, comment, and type @Codex (or another agent) to ask it something";
3. how to stop it (`margin stop`, or `margin undeploy cloudflare`) and where the data lives.

## Removing Margin

- Local hub: `margin stop`, then delete `~/.margin` (all docs and keys).
- The skills: `margin skills remove` (before uninstalling the CLI).
- Cloudflare: `margin undeploy cloudflare --name <name>` deletes the Worker and its data, and the keys on this machine.
- The CLI: `npm uninstall -g margin-hub`.

## Safety rules

- Keys (`access key`, `computer secret`, `sk_agent_…` tokens) don't go in chat, commits or command
  arguments. Margin keeps them in files with mode 600; pass them with `--key-file`, stdin, or a hidden prompt.
- A hub reachable from the internet must have an access key. Margin makes one automatically for
  `--public` and for Cloudflare.
- Don't sign in to anything for the user. They run `npx wrangler login`, `codex login`, `ssh` setup themselves.
- Agents are locked down by default: woken agents get only the Margin tools (Claude Code: no built-in
  tools and none of the user's MCP servers; Codex: a sandbox with no file or network access), and the
  hub only lets an agent act where the request that woke it points. Leave agents at that scope unless
  the user fully trusts one; suggest `--quarantine` for agents that read docs from outside their team.
  Background: https://github.com/LLTOMZHOU/margin/blob/main/docs/SECURITY.md
Files in this package (5)
  • SKILL.md 5 KB
  • reference/agents.md 3 KB
  • reference/cloudflare.md 2 KB
  • reference/local.md 2 KB
  • reference/vps.md 2 KB

Versions

The database has no other skills named margin-setup.

Database snapshot: 13.11.2026 · package version 6d3a7a3282e1 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100host-connect
    Use when the user wants work to run on their VPS or another machine, or a host is missing or broken in team_host. Walks them through connecting it.
  • 100cloudflare-vps-prep
    Configure the Cloudflare account prerequisites for the vps-ss Docker installer through the live dashboard, then generate a validated cloudflare-vps-prep.json file. Use when the user asks to prepare Cloudflare Workers credentials/materials for a VPS, automate the Cloudflare-side…
  • 90install-open-mail-server
    Installs Open Mail Server on a Linux VPS over SSH. Asks for the server host, username, and password, installs Docker when it is missing, copies this project and its Compose file, and starts the container. Use when the user asks to install, deploy, or set up Open Mail Server on a…
  • 100cloudflare-deploy
    Deploy applications and infrastructure to Cloudflare using Workers, Pages, and related platform services. Use when the user asks to deploy, host, publish, or set up a project on Cloudflare.
  • 95cloudflare-deploy
    Deploy applications and infrastructure to Cloudflare using Workers, Pages, and related platform services. Use when the user asks to deploy, host, publish, or set up a project on Cloudflare.
  • 100vps-panel-3xui
    在一台 Linux VPS 上全自动部署、重装或迁移 3x-ui(x-ui)代理面板——SSH 探测、非交互安装、验收、备份数据库、凭据落盘一次做完。当用户提供 VPS 的 IP / SSH 端口 / root 密码,并说"搭面板""装 3x-ui""节点面板""重装面板""续费后恢复面板""帮我配代理服务器"时使用;也用于排查面板打不开、密码登不上、端口不通、HTTP/HTTPS 协议混淆等问题。

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.