Dev Server

Local project files sync to an isolated cloud dev session through connic dev.

The connic dev command creates an isolated cloud dev environment, syncs the local project, and watches supported files for edits. Synced agent code changes are available to the next agent invocation. It supports:

• Test synced edits: save a file, trigger an agent, and inspect the result
• Use connectors: configure webhooks, cron jobs, Telegram, and other connectors in the dev environment
• Work from the editor: local saves sync directly to the dev session
• Stay isolated from production: dev runs in its own environment with its own API keys, env vars, and connectors

Quick Start

1. 1

   Authenticate

   Run connic login in the project root. The CLI opens the dashboard to create an API key, then prompts for the login token to paste back.

   terminal

   Copy

   connic login

   Credentials are saved to .connic. Add the file to the project's .gitignore.

2. 2

   Start a Dev Session

   Run the command without arguments. A reusable environment is selected by default. Use Up/Down to move and Enter to select. Enter a name for a new reusable environment, or choose a quick test for a temporary environment.

   terminal

   Copy

   # Choose a reusable dev environment or a quick test
   connic dev

   The CLI saves the preferred reusable environment in .connic. When valid, it appears first and is selected by default on the next run. Quick tests leave this preference unchanged. The CLI uploads the project and starts watching supported files.

3. 3

   Develop and Iterate

   Edit the agent YAMLs, tools, middleware, or tool hooks. The CLI uploads on each save (debounced ~1s). Use the dashboard's connectors page or the agent detail page to trigger agents and inspect runs in real time.

   In an interactive terminal, use these single-key controls:

   • r uploads the current files immediately
   • t runs the suites in tests/ against the active dev environment
   • q stops the session and runs its normal cleanup

   If single-key controls are unavailable, press Ctrl+C to stop the session.

Ephemeral vs Named Environments

The interactive prompt offers both session types. To select one directly, use --quick or pass a name. Use an explicit choice for unattended runs. The choice determines whether the underlying environment, its connectors, and its env vars persist after the session exits.

connic dev --quick

# Reuse a named dev environment across sessions
connic dev my-feature

File Watching

The CLI watches the standard project directories for changes:

Saves are debounced for 1 second so a multi-file rename or formatter pass uploads as one batch. Subfolders inside agents/ and tools/ are watched recursively, so larger projects can split files into namespaces without changing anything.

Dashboard Integration

Dev environments appear alongside the standard environments:

• Environment switcher: dev environments are grouped separately from standard environments
• Agents view: shows the agents available in the dev session
• Connectors: create and trigger them in the selected dev environment
• Deployments page: the dev session has a Dev session badge that identifies it in the list

The .connic file in the project root stores credentials and the preferred reusable dev environment. A credentials-only file looks like this:

{
  "api_key": "cnc_xxxxxxxxxxxx",
  "project_id": "your-project-uuid"
}

Credentials can also be passed through environment variables, which is useful for CI or shared shells where a checked-in file would be wrong:

# Environment variables
CONNIC_API_KEY=cnc_xxxxxxxxxxxx
CONNIC_PROJECT_ID=your-project-uuid

Conflict Handling

Only one dev session can be active per named environment at a time. Starting a second session against the same name returns:

Use a different name or choose a quick test to work in parallel.