Local Testing
Develop and test your agents locally with hot-reload. See changes reflected in 2-5 seconds without pushing to git.
Overview
Fast iteration for agent development
The connic test command creates an isolated development environment in the cloud and syncs your local files automatically. This lets you:
- Iterate quickly: Changes are synced and applied in 2-5 seconds
- Test with real connectors: Use your project's connectors to trigger agents
- No git commits needed: Develop locally without polluting your commit history
- Isolated environment: Test environments are separate from production
Prerequisites
• Connic SDK installed: pip install connic-composer-sdk
• API key created in the dashboard (Project Settings → CLI)
• A valid agent project with at least one agent in agents/
Quick Start
Create an API Key
Authenticate
Run the login command in your project directory. It will prompt for your API key and project ID.
connic loginThis creates a .connic file with your credentials. Add it to your .gitignore!
Start a Test Session
Start a test session to upload your files and begin development.
# Start an ephemeral test session (auto-deleted on exit)
connic testThe CLI will upload your files, start a container, and watch for changes.
Develop and Test
Edit your agent files, tools, or middleware. Changes are automatically detected and synced. Use connectors in the dashboard to trigger your agents and test them.
Press Ctrl+C to stop the session.
Ephemeral vs Named Environments
Test sessions can be ephemeral (temporary) or named (persistent).
Ephemeral
connic test- • Auto-deleted when session ends
- • Fresh start every time
- • Good for quick experiments
Named
connic test my-feature- • Persists after session ends
- • Reuse the same environment
- • Good for ongoing feature work
File Watching
The CLI watches specific directories and files for changes:
my-agent-project/
├── agents/ # ✓ Watched
│ └── assistant.yaml
├── tools/ # ✓ Watched
│ └── calculator.py
├── middleware/ # ✓ Watched
│ └── assistant.py
├── requirements.txt # ✓ Watched
└── .connic # Auth config (not synced)When any watched file changes, the CLI waits 1 second for additional changes (debouncing), then uploads all files to the test container. The container automatically reloads the agents.
Tip: If you add new dependencies to requirements.txt, they are automatically installed when the file is synced.
Dashboard Integration
Test environments appear in the dashboard alongside your regular environments:
- Environment dropdown: Dev environments are shown in a separate section with orange styling
- Agents tab: Shows agents from your current test session
- Connectors: Create and test connectors with your dev environment selected
- No deployments tab: Deployments are hidden for dev environments since code is synced directly
When no active session is running for a dev environment, the dashboard shows instructions to start one.
Configuration
Authentication via file or environment variables
The .connic file stores your credentials:
{
"api_key": "cnc_xxxxxxxxxxxx",
"project_id": "your-project-uuid"
}Alternatively, use environment variables:
# Environment variables
CONNIC_API_KEY=cnc_xxxxxxxxxxxx
CONNIC_PROJECT_ID=your-project-uuidConflict Handling
Only one test session can be active for a named environment at a time. If you try to start a second session with the same name, you'll see an error:
Error: A test session is already active for this environment. Stop the existing session first with Ctrl+C.
This prevents conflicts from multiple developers working on the same named environment. Use unique names or ephemeral sessions to avoid this.
Ready to develop!
With connic test, you can iterate on your agents in seconds instead of minutes.