Managing Workspaces

Workspaces contain your project files, configurations, and context that your agents need to run. Upload your workspace once, then reference it in any job.

What is a Workspace?

A workspace is a directory structure containing:

Source code
Configuration files
Runbooks and documentation
Scripts and tools
Environment variables
Any files your agent needs access to

Creating a Workspace

Structure Your Files

Organize your workspace with a clear structure:

my-agent-workspace/
├── README.md              # Documentation
├── .env                   # Environment variables
├── runbooks/              # Operational guides
│   ├── setup.md
│   └── troubleshooting.md
├── scripts/               # Utility scripts
│   └── deploy.sh
└── config/                # Configuration files
    └── settings.json

Upload via API

# Compress your workspace
tar -czf workspace.tar.gz my-agent-workspace/

# Upload to Knify
curl -X POST https://api.knify.io/workspaces \
  -H "Authorization: Bearer $KNIFY_API_KEY" \
  -F "workspace=@workspace.tar.gz" \
  -F "name=my-agent-workspace"

Response:

{
  "workspace_id": "ws_abc123",
  "name": "my-agent-workspace",
  "path": "/workspaces/my-agent-workspace",
  "created_at": "2025-11-17T10:30:00Z"
}

Using Workspaces in Jobs

Reference your workspace by path:

curl -X POST https://api.knify.io/jobs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KNIFY_API_KEY" \
  -d '{
    "spec": {
      "job_type": "cursor_task",
      "prompt": "Review the runbooks in this workspace",
      "workspace_path": "/workspaces/my-agent-workspace"
    }
  }'

The agent will have access to all files in the workspace.

Pre-Configured Workspaces

Knify includes several pre-configured workspaces for common use cases:

FH E2E Tools

For end-to-end testing and user creation workflows:

curl -X POST https://api.knify.io/jobs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KNIFY_API_KEY" \
  -d '{
    "spec": {
      "job_type": "fh_e2e_tools",
      "prompt": "Create a test user",
      "workspace_path": "/workspaces/fh-e2e-tools"
    }
  }'

Includes:

Playwright test scripts
Checkout token utilities
QA runbooks
Pre-configured browser automation

Workspace Features

Environment Variables

Store sensitive configuration in .env files:

# .env in your workspace
DATABASE_URL=postgresql://localhost/mydb
API_KEY=secret_key_here
STRIPE_KEY=sk_test_...

These variables are automatically loaded when the job runs.

Security: Never commit real secrets to workspaces. Use environment variable injection via job spec instead.

Runbooks

Markdown files that guide the agent's execution:

# Create User Runbook

1. Navigate to signup page
2. Fill in user details
3. Submit form
4. Verify email sent
5. Activate account

Reference runbooks in your prompts:

{
  "spec": {
    "job_type": "cursor_task",
    "prompt": "Follow the steps in @create-user.md to create a new user"
  }
}

Configuration Files

JSON, YAML, or TOML files for your agent's settings:

{
  "timeout": 300,
  "retries": 3,
  "strict_mode": false
}

Managing Workspaces

List Workspaces

curl https://api.knify.io/workspaces \
  -H "Authorization: Bearer $KNIFY_API_KEY"

Get Workspace Details

curl https://api.knify.io/workspaces/{workspace_id} \
  -H "Authorization: Bearer $KNIFY_API_KEY"

Update Workspace

Upload a new version:

tar -czf workspace-v2.tar.gz my-agent-workspace/

curl -X PUT https://api.knify.io/workspaces/{workspace_id} \
  -H "Authorization: Bearer $KNIFY_API_KEY" \
  -F "workspace=@workspace-v2.tar.gz"

Delete Workspace

curl -X DELETE https://api.knify.io/workspaces/{workspace_id} \
  -H "Authorization: Bearer $KNIFY_API_KEY"

Best Practices

1. Keep Workspaces Lean

Only include files your agent needs. Smaller workspaces upload and mount faster.

# Use .gitignore patterns
node_modules/
.venv/
*.pyc
__pycache__/

2. Version Your Workspaces

Use meaningful names for tracking:

curl -X POST https://api.knify.io/workspaces \
  -F "workspace=@workspace.tar.gz" \
  -F "name=my-agent-v1.2.3"

3. Document Everything

Include README files to guide the agent:

# My Agent Workspace

## Purpose
This workspace contains tools for automated user testing.

## Files
- `runbooks/` - Step-by-step guides
- `scripts/` - Utility scripts
- `config/` - Configuration files

## Usage
Reference runbooks in your prompts using @filename.md syntax.

4. Separate Concerns

Create different workspaces for different tasks:

testing-workspace - For E2E tests
analysis-workspace - For code analysis
deployment-workspace - For deployment automation

5. Use Relative Paths

Always use relative paths within your workspace:

# Good
with open("config/settings.json") as f:
    config = json.load(f)

# Bad
with open("/absolute/path/to/config.json") as f:
    config = json.load(f)

Workspace Persistence

Files created during job execution persist in the sandbox:

Job 1: Creates output.txt
Job 2 (continuation): Can read and modify output.txt
Job 3 (continuation): Still has access to all previous files

Files persist for up to 30 days in paused sandboxes. After cleanup, all files are deleted.

Example: Multi-File Workspace

e2e-testing-workspace/
├── README.md
├── .env
├── runbooks/
│   ├── create-user.md
│   ├── login-flow.md
│   └── checkout-process.md
├── playwright/
│   ├── auth.setup.ts
│   ├── user.spec.ts
│   └── checkout.spec.ts
├── checkout_token/
│   ├── generate.mjs
│   └── verify.mjs
└── config/
    ├── playwright.config.js
    └── test-data.json

Using this workspace:

curl -X POST https://api.knify.io/jobs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KNIFY_API_KEY" \
  -d '{
    "spec": {
      "job_type": "fh_e2e_tools",
      "prompt": "Run the full checkout process using @checkout-process.md",
      "workspace_path": "/workspaces/e2e-testing"
    }
  }'

The agent has access to all files and can:

Read runbooks for guidance
Execute Playwright tests
Generate checkout tokens
Access test data

Next: Templates

Learn about sandbox templates and optimization.