Host Environment Setup Checklist

Table of Contents

Purpose

Quick checklist for rebuilding the surrounding environment (accounts, config, skills, prompts, permissions) that sit outside any git clone.

Accounts and permissions

  • Create or identify the human login and the agent login (defaults: human = ligon, agent = coder, group = coder). The coder account is a shared Unix user—any supported agent binary (Codex, Claude Code, Gemini CLI, etc.) runs under it.
  • Make sure the agent group can read (not write) the human config directory and skills checkout.
  • Prefer agent mirrors under a writable temp location (default /var/tmp/coder-mirrors) owned by the human with group access for coder.

Sudo access

sucoder requires the human user to have sudo access to run commands as the agent user (coder). If you are running directly as the agent user (e.g., inside a container), pass --no-agent-sudo to all sucoder commands to skip sudo.

Creating the agent account (root required)

  • Create the group (idempotent) and user if they do not exist: 

    sudo groupadd -f coder
id -u coder || sudo useradd -m -s /bin/bash -g coder -G coder coder
sudo passwd -l coder  # lock password; use sudo/su for elevation when needed

  • Ensure the home directory exists at /home/coder and has sane perms: 

    sudo chmod 755 /home/coder
  • Makefile helper: make create-agent-user runs the above with sudo (or SUDO override).
  • The default make target now runs user creation before seeding config/skills, so run it as a user with sudo access.

Core directories

  • ~/.sucoder: config + symlinks. Require group-read, no group-write.
  • ~/.sucoder/skills: symlink to skills checkout (see below).
  • ~/.sucoder/system_prompt.org: global system prompt loaded before sessions.
  • Optional logs: /home/ligon/.sucoder/logs (or another path referenced in config).

Configuration

  • Copy config.example.yaml (or default_config.yaml) to ~/.sucoder/config.yaml and adjust:
    • human_user, agent_user, agent_group
    • mirror_root path for agent mirrors
    • skills default path(s)
    • system_prompt path (global prompt)
    • per-mirror entries: canonical repo path, mirror name, base branch, branch prefixes, agent launcher flags (including nvm settings if needed)

  • Fix permissions after editing: 

    sudo chgrp coder ~/.sucoder ~/.sucoder/config.yaml
sudo chmod 750 ~/.sucoder
sudo chmod 640 ~/.sucoder/config.yaml

Skills repository

  • Clone the skills repo somewhere the human owns, e.g.: 

    git clone https://github.com/ligon/sucoder-skills ~/Projects/sucoder-skills
ln -s ~/Projects/sucoder-skills ~/.sucoder/skills
sudo chgrp -R coder ~/Projects/sucoder-skills
sudo chmod -R g+r ~/Projects/sucoder-skills
sudo chmod -R g-w ~/Projects/sucoder-skills

  • Warm up discovery to catch permission issues early: 

    ls ~/.sucoder/skills
sucoder skills-list

    To preload the catalog into a session, use the agent's file-read command (e.g., codex read ~/.sucoder/skills/SKILLS.md for Codex).

System prompt

  • Start from default_system_prompt.org or your own content: 

    cp default_system_prompt.org ~/.sucoder/system_prompt.org
# edit to add local norms, commands to run on session start, escalation rules, etc.
  • Ensure group-read access for the agent.

Tooling prerequisites

  • Python + Poetry (for sucoder CLI): poetry install inside the project to get dependencies and run poetry run sucoder --help.
  • Node via nvm if you want to pin the agent's Node runtime; configure agent_launcher.nvm in the mirror config when used.
  • Agent CLI (Codex, Claude Code, Gemini CLI, etc.) installed and callable for the human; sucoder injects the appropriate write-access flag automatically when launching agents (e.g., --yolo for Codex; see the flag template table in README.org).

Mirror preparation flow (per project)

  • Prepare canonical repo permissions and optional coder remote: 

    sucoder prepare-canonical <mirror-name> [--sudo]

  • Clone or refresh the agent mirror: 

    sucoder agents-clone <mirror-name> --verbose
sucoder sync <mirror-name>

  • Create a task branch for the agent: 

    sucoder start-task <mirror-name> <task> --base <human-branch>

Verification checks

  • sucoder mirrors-list shows configured mirrors and paths.
  • sucoder status <mirror-name> confirms remotes, branch prefixes, and permissions.
  • pytest from the repo root verifies the CLI locally.

Optional niceties

  • Add shell completion for sucoder if your shell supports it.
  • Keep a scratch note (Org/Markdown) of local norms and upload it to the system prompt when it changes.
  • Use the top-level Makefile to automate setup on a new host:
    • make env-setup (create agent user, ensure Poetry, seed config + prompt, clone + link skills, set permissions)
    • make warmup (run discovery checks)
    • make poetry-ensure (install Poetry for the agent user if missing; reminds to add ~/.local/bin to PATH) — also runs as part of env-setup
    • make poetry-install / make test for project dependencies and validation.

SuCoder — Home · GitHub