Skip to main content
Connic
Test

Dev Server

Use connic dev to sync local project files to an isolated cloud dev session.

Last updated
On this page

Overview

Develop directly from local project files

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

  • Test synced edits: save a file, trigger your agent, and inspect the result
  • Use connectors: configure webhooks, cron jobs, Telegram, and other connectors in the dev environment
  • Work from your 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
Prerequisites

• Connic SDK installed: pip install connic-composer-sdk

• A valid agent project with at least one agent in agents/

Quick Start

1

Authenticate

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

terminal
connic login

Credentials are saved to .connic. Add the file to your .gitignore.

2

Start a Dev Session

Start a session to create a dev environment and upload your files.

terminal
# Start an ephemeral dev session (auto-deleted on exit)
connic dev

The CLI uploads your project and starts watching supported files.

3

Develop and Iterate

Edit your 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 your 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

Dev sessions can be ephemeral or named. The choice changes whether the underlying environment, its connectors, and its env vars persist after you exit.

Ephemeral
terminal
connic dev
  • • Auto-deleted when you exit with q or Ctrl+C
  • • Fresh environment every run
  • • Best for quick experiments and bug repros
Named
terminal
# Reuse a named dev environment across sessions
connic dev my-feature
  • • Persists when you exit with q or Ctrl+C
  • • Reattach later with the same name
  • • Best for ongoing feature work where connectors and env vars matter

File Watching

The CLI watches the standard project directories for changes:

Project structure
my-agent-project/
agents/✓Watched
assistant.yaml
tools/✓Watched
calculator.py
middleware/✓Watched
assistant.py
hooks/✓Watched
assistant.py
schemas/✓Watched
guardrails/✓Watched
tests/✓Watched (press 't' to run)
requirements.txtInstalled when the session starts
.connicAuth config (not synced)

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.

Dependencies from requirements.txt are installed when the dev session starts. Stop and recreate the session after changing this file.

Dashboard Integration

Dev environments appear alongside your 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 shows up with a Dev session badge so you can spot it in the list

Configuration

Authentication via file or environment variables

The .connic file in your project root stores your credentials:

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

You can also pass them through environment variables, useful for CI or shared shells where a checked-in file would be wrong:

.env
# 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:

Error: A dev session is already active for this environment. Stop the existing session first with q or Ctrl+C in the terminal where it is running.

Use a different name, or omit it for an ephemeral session, to work in parallel.

Continue testing

Testing Framework

Write declarative test suites in tests/

Deployment

Ship to production via git or CLI

Agent Configuration

Configure your agents in YAML

Webhooks

Trigger agents via HTTP webhooks