Remote agent runs¶

Your agent finished the work. Now the Markdown needs somewhere to live.

This is one of the cleanest OpenDocs workflows: an agent runs on a server, writes useful Markdown artifacts, and publishes them without you needing to copy files back to your laptop or dig through terminal logs.

The problem¶

Remote agents are great at long-running work:

• Refactor a codebase.
• Analyze a repo.
• Generate migration notes.
• Summarize test failures.
• Produce a security review.
• Write implementation docs after a task finishes.

But the output often lands in an awkward place: a file on a server, a CI artifact, a terminal buffer, or a Markdown report attached to a run. That is fine for machines and annoying for people.

You want a link you can open, share, comment on, and come back to later.

The OpenDocs workflow¶

Create a project for the run or the recurring workflow:

opendocs project create "Remote agent reports" --slug remote-agent-reports --use

Then have the agent publish the output folder:

opendocs publish ./agent-output --tags agent,remote-run --visibility public --confirm-public

For internal work, skip public visibility:

opendocs publish ./agent-output --tags agent,remote-run

The default visibility is workspace, so your team can read it and the public cannot.

What the team gets¶

• A stable URL for every generated report.
• A project page that groups the full run.
• Searchable Markdown with clean typography.
• Downloadable PDF and DOCX exports when the report needs to travel.
• Version history when the same report gets updated.

Instead of "go SSH into the box and check the output file", you get:

https://opendocs.cc/acme/projects/remote-agent-reports/api-review

That is a better handoff.

When to use this¶

Use OpenDocs for remote agent runs when the output needs to be read by a human:

• nightly codebase summaries
• dependency upgrade reports
• architecture reviews
• incident reconstruction notes
• QA findings
• compliance scans
• generated customer handoff docs

If the output is only for another script, keep it as a raw artifact. If a person needs to read it, publish it.

Why projects matter here¶

Remote agents can produce a lot of documents quickly. Putting those docs into a project keeps the workspace from turning into one long mixed feed.

The Default project stays clean. The agent run gets its own home. Readers can browse the project, filter by tags, or download what they need.

That is the shape OpenDocs is built for.