agentleFS
0-CYBERDYNE-SYSTEMS-00-CYBERDYNE-SYSTEMS-0/FFT_nano/skills/setup/debug/SKILL.md

debug

Skill4 starsChanged 8 months agoMITView on GitHub

Debug FFT_nano agent runtime issues (Docker default, host opt-in). Use when agent execution fails, runtime checks fail, or onboarding/startup is blocked.

  • Reads credentials

191 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use add-discord, add-slack and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • MicrosoftSkill

    add-discord

    Add Discord bot channel integration via Chat SDK.

    Also in 11 projects that use this

  • MicrosoftSkill

    add-slack

    Add Slack channel integration via Chat SDK.

    Also in 11 projects that use this

  • +10 more from microsoft

The file

We split this skill into the rules it gives an agent

7 rules. 0 are common, 7 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 177 edited versions we read keep these.

  • 7

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Do not use for feature development or planned refactors.

    line 14
  2. Distinctive:

    Do not use for normal chat operations when the runtime is healthy.

    line 15
  3. Distinctive:

    Start Docker Desktop / Docker daemon.

    line 86
  4. Distinctive:

    Check newest runtime log:

    line 95
  5. Distinctive:

    Verify per-group session mount path exists:

    line 107
  6. Distinctive:

    Ensure runtime logs show expected mounted session directory and no permission errors.

    line 112
  7. Distinctive:

    If issue persists, capture and share:

    line 157

“Common” is measured: kept by at least 6 in 10 of the 177 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

FFT_nano Runtime Debugging

This guide covers host-side diagnosis for current runtime modes:

  • Docker (default)
  • Host runtime (advanced, explicit opt-in)

When not to use this skill

  • Do not use for feature development or planned refactors.
  • Do not use for normal chat operations when the runtime is healthy.

Runtime Architecture

Host process (src/index.ts -> src/wiring.ts)
  -> runtime selection (src/container-runtime.ts)
  -> agent execution (src/container-runner.ts)
     - Docker mode: docker run fft_nano-agent:latest
     - Host mode: node container/agent-runner/dist/index.js

Key Log Locations

LogLocationPurpose
App loglogs/fft_nano.logRouter, scheduler, runtime orchestration
App error loglogs/fft_nano.error.logHost process failures
Runtime run loggroups/<folder>/logs/runtime-*.logPer-run stdout/stderr, mounts, env diagnostics

Quick Health Checks

1) App build/runtime sanity

npm run typecheck
npm run build

2) Runtime mode resolution

node -e "import('./dist/container-runtime.js').then(m=>console.log(m.getContainerRuntime()))"

3) Docker availability (default)

docker --version
docker info >/dev/null && echo "Docker OK" || echo "Docker NOT running"

4) Host mode gating (advanced)

grep -E '^(CONTAINER_RUNTIME|FFT_NANO_ALLOW_HOST_RUNTIME|FFT_NANO_ALLOW_HOST_RUNTIME_IN_PROD)=' .env || true

Host mode requires:

  • CONTAINER_RUNTIME=host
  • FFT_NANO_ALLOW_HOST_RUNTIME=1

Production host mode additionally requires:

  • FFT_NANO_ALLOW_HOST_RUNTIME_IN_PROD=1

Common Failure Modes

"Invalid CONTAINER_RUNTIME"

Cause: .env contains an unsupported value.

Fix:

sed -i.bak 's/^CONTAINER_RUNTIME=.*/CONTAINER_RUNTIME=auto/' .env

"No supported runtime found"

Cause: Docker unavailable and host mode not explicitly allowed.

Fix options:

  1. Start Docker Desktop / Docker daemon.
  2. Or explicitly enable host mode in .env:
CONTAINER_RUNTIME=host
FFT_NANO_ALLOW_HOST_RUNTIME=1

Runtime exits with code 1

Check newest runtime log:

ls -t groups/*/logs/runtime-*.log | head -1 | xargs -I{} sh -lc 'echo "== {} =="; tail -120 "{}"'

Then validate credentials:

grep -E '^(CLAUDE_CODE_OAUTH_TOKEN|ANTHROPIC_API_KEY|PI_API|PI_MODEL|ZAI_API_KEY)=' .env

Session resumption problems

Verify per-group session mount path exists:

ls -la data/pi/main/.pi 2>/dev/null || true

Ensure runtime logs show expected mounted session directory and no permission errors.

Manual Runtime Smoke Tests

Docker mode smoke

echo '{}' | docker run -i --entrypoint /bin/echo fft_nano-agent:latest "Container OK"

Host mode smoke

npm --prefix container/agent-runner run build
CONTAINER_RUNTIME=host FFT_NANO_ALLOW_HOST_RUNTIME=1 FFT_NANO_DRY_RUN=1 npm run dev

Service-level Checks (launchd)

launchctl list | grep fft_nano || true
launchctl kickstart -k gui/$(id -u)/com.fft_nano
sleep 2
tail -80 logs/fft_nano.log

One-Pass Diagnostics Script

echo "1) Node/build"
node --version
npm run -s build >/dev/null && echo "build OK" || echo "build FAIL"

echo "\n2) Docker"
docker info >/dev/null 2>&1 && echo "docker OK" || echo "docker NOT ready"

echo "\n3) Runtime policy"
grep -E '^(CONTAINER_RUNTIME|FFT_NANO_ALLOW_HOST_RUNTIME|FFT_NANO_ALLOW_HOST_RUNTIME_IN_PROD)=' .env || echo "no runtime env overrides"

echo "\n4) Latest runtime logs"
ls -t groups/*/logs/runtime-*.log 2>/dev/null | head -3 || echo "no runtime logs yet"

Escalation Data to Capture

If issue persists, capture and share:

  1. logs/fft_nano.log tail (last 120 lines)
  2. Latest groups/<folder>/logs/runtime-*.log
  3. Output of docker info (or host mode env flags)
  4. Current .env runtime keys (redact secrets)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.