Get your first run in Sulcus.

Pick where your agent runs, follow that path, and check the requirements before you start.

An account, and a path.

Create an account with Google, GitHub or email, and verify your email address when asked. You get a workspace for your projects and runs.

Sulcus is in early access. Anyone can sign up, verify their email and run an agent from a public GitHub repo, within daily usage limits. Hosted runs support LangGraph, CrewAI, OpenAI Agents SDK and Google ADK. Connecting Claude Code, Codex, Cursor, a deployed Google ADK service or Microsoft Copilot Studio doesn’t depend on hosted access. Claude Code, Codex and Cursor are in early access, and the Sulcus CLI they need is provided on request.

Hosted by Sulcus

Run a repository in five steps.

  1. Try the built-in example

    Under New run, choose Built-in example where it’s offered. It runs offline, needs no API key, and shows what a run looks like.

  2. Create a project

    Enter the public HTTPS repository URL, a branch, tag or commit, the Python file to run, the framework and how to install dependencies. Sulcus checks the repository, branch and file before your first run.

  3. Start a run

    Add the API keys your app reads from its environment, such as your model provider’s key, and optionally a token limit for this run.

  4. Watch Run Details

    Follow agents and steps, model and tool activity, token usage and issues as they arrive.

  5. Stop or inspect

    Stop the run at any time. When it ends, the outcome, event history and resolved commit stay with the run.

What happens when you start a run

  1. ResolveCopies the project’s current configuration into the new run.
  2. ValidateChecks the HTTPS repository URL, Git reference, Python entrypoint, framework and dependency mode.
  3. Check outClones the repository inside the run’s container, resolves the reference to an exact commit and installs dependencies.
  4. InstrumentTurns on the instrumentation for the framework you selected.
  5. RunStarts your entrypoint with the API keys you added, fixed CPU, memory and time limits, and outbound network access.
  6. StreamSends ordered, redacted events and your app’s output to Run Details as they happen, and applies the token limit if you set one.
  7. RetainKeeps the configuration snapshot, resolved commit, timestamps, outcome, token totals and a bounded event history.

Run again, on a finished run that belongs to a project, opens New run for that project: the new run uses the project’s current settings, resolves the Git reference again and needs its API keys again.

A normal entrypoint.

Sulcus runs your file the way python app.py would, so code under if __name__ == "__main__": executes. Invoke your graph, crew or agent the way you already do.

Put langgraph and your model provider’s package in a requirements.txt or pyproject.toml at the repository root.

This sample is the smallest graph that runs. To see model calls and token counts, call a model from a node and add its API key to the run.

app.py
# app.py: runs as-is as a hosted run, with no Sulcus imports.
# It makes no model call, so it needs no API key and reports no tokens.
from typing import TypedDict
from langgraph.graph import StateGraph, START, END

class State(TypedDict):
    question: str
    answer: str

def answer(state: State) -> dict:
    return {"answer": f"You asked: {state['question']}"}

graph = StateGraph(State)
graph.add_node("answer", answer)
graph.add_edge(START, "answer")
graph.add_edge("answer", END)
app = graph.compile()

if __name__ == "__main__":
    # Anything printed here is kept with the run.
    print(app.invoke({"question": "What does Sulcus see?"}))

Requirements for hosted runs

What Sulcus needs from your repository.

SettingWhat’s supportedNotes
RepositoryPublic HTTPS Git URLPrivate repositories, SSH URLs and credentials in the URL aren’t supported.
ReferenceBranch, tag or commitSulcus resolves it to an exact commit and records it with the run.
File to runRelative path to a Python fileMust be inside the repository. It runs as __main__.
LanguagePython 3.12Other languages aren’t supported for hosted runs.
FrameworkLangGraph, CrewAI, OpenAI Agents SDK or Google ADKChoose the one your code uses. Supported versions: LangGraph 1.x; CrewAI 1.14 and later 1.x; OpenAI Agents SDK 0.22.2 and later 0.22; Google ADK checked with 1.39.1 and 2.11.0.
DependenciesAuto, requirements, project or noneAuto installs from pyproject.toml if present, otherwise from requirements.txt. Both are read from the repository root.
NetworkOutbound access to the public internetEnough to reach model providers and install packages over HTTPS. There is no per-project domain allowlist. Private network ranges and cloud metadata addresses aren’t reachable, and non-web ports may be blocked.
ResourcesFixed per runThe platform sets CPU, memory and time limits, and limits how many runs a workspace can start. They aren’t configurable; the app tells you when a limit stops a run from starting.

API keys and limits for hosted runs

Set per run.

API keys

Add API keys and other secrets when you start a run. Your app reads them as environment variables. They aren’t saved with the project or the run, and known values are redacted from events and logs on a best-effort basis. Enter them again for each run.

Model usage is billed by your provider, through your own API key. Sulcus shows token counts, not costs.

Token limit

Optionally set a total token limit for the run. Run Details shows usage against it and warns as it approaches. Once reported usage reaches the limit, Sulcus blocks the next model call and ends the run. For Google ADK, the run fails when the script ends instead.

The limit uses the token counts your framework reports. A request already in flight can finish and exceed it. It isn’t a ceiling on what your provider bills.

Application output

What your app prints to stdout and stderr is kept with the run, up to a limit, so you can read it in Run Details. Don’t print prompts, responses or personal data you wouldn’t want stored.

Stopping a run

Use Stop run in Run Details to end an active hosted run and its container. Stopping can’t undo a side effect that already happened.

When a hosted run fails.

Run Details groups errors into a named cause, explains it in plain language and keeps the technical details, logs and recorded activity that led up to the failure.

  • Project preparation failed
  • Framework setup failed
  • Agent execution failed
  • AI usage limit exceeded
  • AI provider rejected the API key
  • Provider usage limit reached
  • Run time limit exceeded
  • Resource limit exceeded

Provider errors are reported as the provider’s, not as a Sulcus intervention.

Frameworks

What Sulcus observes in each one.

Coverage follows each framework’s public entry points, hooks and callbacks, so how much you see differs: CrewAI exposes less structure than LangGraph. Provider-hosted tools and internal retries may not be visible.

Usage a framework doesn’t report stays unknown. Plain Python scripts and other frameworks aren’t supported for hosted runs: select the framework your application actually uses.

On your computer

Claude Code, Codex and Cursor.

All three integrations require the Sulcus CLI on the computer where the agent runs.

These integrations are in early access, and the Sulcus CLI (the app calls it the Sulcus engine) isn’t publicly installable yet. Contact support@sulcus.dev to request it. The commands below assume the Sulcus CLI is already installed.

  • Python 3.10 or later
  • Working native credential storage, such as your operating system’s keychain or credential manager
  • Claude Code, Codex or Cursor, installed and signed in, for the agent you want to connect
  • For Cursor: tested on macOS. Windows isn’t supported yet.

With the Sulcus CLI installed, sulcus login prints a code. Enter it under Computers in the app to pair this computer; only approve a code you requested yourself. sulcus logout disconnects the computer and deletes its stored credential.

By default the CLI sends activity metadata: agent and tool names, status, timing, exit codes and token counts, plus the project folder’s name, a hash of its path and its Git remote address so runs can be grouped by project. Prompts, model responses, command output, file contents and file diffs stay on your computer. When an agent asks for approval, a computer at the default sharing level, decision context, also sends the command (up to 2,000 characters), the working directory, up to 10 affected file paths and, for a network request, the hostname. You set the level on the computer with sulcus device privacy; see Security.

Claude Code

Observe your normal sessions.

Once the CLI is installed and the computer is paired, sulcus claude-code install-hooks adds Sulcus hooks to your Claude Code user settings. After that, use Claude Code as usual: each session appears under Runs.

When Claude Code asks for a permission Sulcus can match to a tool call, the request appears under Approvals. Approve or deny it there. If no decision arrives, Claude Code asks you itself; Sulcus never approves by default.

Stop at next action in Sulcus refuses Claude Code’s next tool call and Claude stops; an idle session’s next prompt is refused instead. Claude Code shows who stopped it.

A stop needs the computer online, the Sulcus companion running and current hooks. Hooks installed before remote stop can’t stop a session: run sulcus claude-code install-hooks again, and sessions started afterwards can be stopped. A stop the computer doesn’t receive within 120 seconds expires, and the app says it wasn’t delivered. If a hook times out or fails, Claude Code carries on. End observation only stops watching. sulcus claude-code uninstall-hooks removes the hooks.

Terminal, with the Sulcus CLI installed
sulcus login
sulcus claude-code install-hooks
claude
Experimental

Start Codex through Sulcus.

Once the CLI is installed and the computer is paired, run sulcus local start in your project folder. It asks for the prompt there and doesn’t send it to Sulcus, then starts Codex and reports the session as a run.

Codex’s command and file-change approval requests wait under Approvals. If nobody decides in time, the request is declined.

Only sessions started this way are observed. Interrupt turn in Sulcus ends the current turn; if it hasn’t ended 5 seconds later, the Codex process is ended. Like any stop from Sulcus, it needs the computer online. This follows Codex’s documentation and hasn’t been verified against an installed Codex yet. This path is early and may change.

Terminal, with the Sulcus CLI installed
sulcus login
sulcus local start
Preview

Observe Cursor conversations.

Once the CLI is installed and the computer is paired, sulcus cursor install-hooks adds Sulcus hooks to ~/.cursor/hooks.json, keeping any hooks already there. Each Cursor conversation then appears as a run. sulcus cursor status checks the hooks, and sulcus cursor uninstall-hooks removes them.

Sulcus sees Cursor’s finished tool calls and turns: each tool’s name, status and duration, and a turn’s token counts and model. It never receives the prompt, a command or its output, a file path or file contents.

Observation only: Sulcus asks for no approvals and can’t stop Cursor; End observation only stops watching. Tested with Cursor 3.24.18 on macOS.

Terminal, with the Sulcus CLI installed
sulcus login
sulcus cursor install-hooks
sulcus cursor status

Deployed elsewhere

Google ADK and Microsoft Copilot Studio.

Google ADK. Under Projects, choose Connect Google ADK. Sulcus shows an endpoint and a one-time token. Add the OpenTelemetry OTLP exporter to your service, set three environment variables and deploy. Each invocation appears as a run after it finishes. Full steps and limits.

Microsoft Copilot Studio. In Microsoft, send your environment’s data to Application Insights and give an app registration the Reader role on that resource. Then, under Projects, choose Connect Copilot Studio and enter the tenant, environment and Application Insights IDs, the client ID and its client secret. Conversations appear as runs, usually within a few minutes. Requirements and limits.

Both are observed only: Sulcus can’t start, stop or limit an agent that runs elsewhere. Their runs show only what was reported: a Google ADK run appears once its invocation finishes or its trace has been quiet for 10 minutes, and Sulcus reads Copilot Studio’s Application Insights telemetry about once a minute and closes a conversation’s run after 30 minutes without new activity.

Preview

Custom agents, over HTTP.

Custom agents docs

Any agent, with or without a framework, can report its runs to Sulcus over a plain HTTP API, ask a person in Sulcus to approve an action, and learn when someone asks it to stop. Under Integrations, choose Custom agent to create a project and its token.

It’s cooperative: your agent has to call the API, send its own events, ask before acting and check whether a stop was requested. Sulcus can’t stop or block an agent that ignores it.

What Sulcus doesn’t do yet.

Private repositories

Hosted runs use public HTTPS Git repositories. Private repositories, SSH URLs and GitHub App access aren’t supported.

Other languages, hosted

Hosted runs are Python apps built with LangGraph, CrewAI, the OpenAI Agents SDK or Google ADK.

Remote control of local agents

Sulcus can answer an approval request from Claude Code or Codex and ask either to stop, but only while the computer is online. It can’t pause or restart the agent on your computer, or stop Cursor.

Policies and hosted approvals

There is no configurable policy engine, and hosted runs have no approval workflow. Approvals are decisions you make yourself, one at a time, for local and custom agents.

Not available yet: configurable run policies, private repositories, saved project secrets, team management.

Ready for your first run?