Environment Types

​

Local Environment (Primary Support)

const agent = await Agent.create({
  config: {
    environment: 'local', // String value, not object
    defaultModel: 'claude-sonnet-3-7',
    // ... other config
  }
});

​

Characteristics

• Fast execution with no container overhead
• Direct file system access to your project
• Simple setup with no additional dependencies
• Native performance for all tool operations

​

Use Cases

• Development and testing environments
• Trusted environments where security isolation isn’t critical
• Performance-critical applications requiring minimal overhead
• Simple deployments without container infrastructure

​

Setup

npm install @qckfx/agent

import { Agent } from '@qckfx/agent';

const agent = await Agent.create({
  config: {
    environment: 'local',
    defaultModel: 'claude-sonnet-3-7',
    tools: ['bash', 'file_read', 'file_write', 'file_edit']
  }
});

​

Docker Environment (Limited Support)

const agent = await Agent.create({
  config: {
    environment: { 
      type: 'docker',
      docker: {
        projectRoot: '/path/to/your/project'
      }
    },
    // ... other config
  }
});

​

Characteristics

• Consistent runtime across different systems
• Security isolation from the host system
• Reproducible environments for testing

• Slower startup due to container initialization
• Additional complexity in setup and maintenance
• Resource overhead from containerization

​

Use Cases

• Security-sensitive environments requiring isolation
• Multi-tenant applications with untrusted code
• Consistent deployment environments across teams
• Testing scenarios requiring clean environments

​

Setup Requirements

1. Docker Installation: Ensure Docker is installed and running
2. Container Configuration: Set up appropriate Docker images
3. Volume Mounting: Configure project directory access
4. Network Configuration: Set up container networking if needed

# Example Docker setup (configuration may vary)
docker build -t qckfx-agent-env .
docker run -v $(pwd):/workspace qckfx-agent-env

​

Remote Environment (Limited Support)

const agent = await Agent.create({
  config: {
    environment: { type: 'remote' },
    // ... other config
  },
  callbacks: {
    getRemoteId: async () => process.env.REMOTE_ID!
  }
});

​

Characteristics

• Maximum isolation from your local system
• Scalable infrastructure managed by the provider
• Consistent environments across different clients

• Network dependency for all operations
• Latency overhead for tool execution
• External service dependency on cloud providers
• Additional costs for cloud sandbox usage

​

Use Cases

• Maximum security isolation requirements
• Scalable multi-tenant applications
• Environments without local compute resources
• Compliance scenarios requiring external execution

​

Environment Selection Guidelines

​

Local Environment

• ✅ Best for: Development, testing, most production use cases
• ✅ When: Performance is critical and security isolation isn’t required
• ✅ Advantages: Fast, simple, fully supported
• ⚠️ Consider: Security implications of running tools with application permissions

​

Docker Environment

• ⚠️ Best for: Security-conscious environments willing to handle potential issues
• ⚠️ When: Isolation is required and you can manage container complexity
• ⚠️ Advantages: Security isolation, consistent environments
• ❌ Drawbacks: Limited support, performance overhead, setup complexity

​

Remote Environment

• ❌ Not recommended: Due to limited support and schema restrictions
• ❌ Current status: Not actively maintained
• ❌ Limitations: Schema only allows ‘local’ environment type

​

Execution Adapter Interface

interface ExecutionAdapter {
  executeCommand(id: string, command: string, workingDir?: string): Promise<CommandResult>;
  readFile(id: string, filepath: string, options?: ReadOptions): Promise<FileContent>;
  writeFile(id: string, filepath: string, content: string): Promise<void>;
  editFile(id: string, filepath: string, searchCode: string, replaceCode: string): Promise<EditResult>;
  listFiles(id: string, path: string, options?: ListOptions): Promise<FileList>;
  findFiles(id: string, pattern: string, options?: FindOptions): Promise<FileList>;
  searchFiles(id: string, pattern: string, options?: SearchOptions): Promise<SearchResults>;
  // ... other methods
}

​

Performance Considerations

​

Local Environment Performance

• Fastest execution with no overhead
• Direct file system access for optimal I/O
• Native process execution for commands
• Minimal memory footprint

​

Docker Environment Performance

• Container startup overhead for each session
• File system mounting may impact I/O performance
• Network overhead for container communication
• Additional memory usage for container runtime

​

Remote Environment Performance

• Network latency for all operations
• Bandwidth limitations for large file operations
• Service availability dependency
• Potential rate limiting from cloud providers

​

Security Considerations

​

Local Environment Security

• Tools run with application permissions
• Direct access to file system and network
• No isolation from host system
• Trust required in tool implementations

​

Docker Environment Security

• Process isolation from host system
• Limited file system access through volume mounts
• Network isolation capabilities
• Container escape risks (though minimal)

​

Remote Environment Security

• Maximum isolation from local system
• Managed security by cloud provider
• Network-only attack surface
• Data transmission security considerations

​

Troubleshooting

​

Local Environment Issues

• Permission errors: Check file system permissions
• Path issues: Verify working directory settings
• Tool failures: Check tool-specific error messages

​

Docker Environment Issues

• Container startup failures: Check Docker configuration
• Volume mounting problems: Verify path mappings
• Network connectivity: Check container networking
• Image compatibility: Ensure proper base images

​

Remote Environment Issues

• Connection failures: Check network connectivity
• Authentication problems: Verify API credentials
• Service availability: Check provider status
• Rate limiting: Monitor usage quotas

​

Migration Between Environments

​

From Local to Docker

• Performance impact: Expect slower execution
• Setup complexity: Requires Docker configuration
• File path changes: May need path adjustments
• Limited support: Prepare for potential issues

​

From Local to Remote

• Currently not possible: Schema restrictions prevent remote environment
• Future consideration: May become available in future versions
• Network dependency: Would require stable internet connection
• Cost implications: Cloud sandbox usage fees

​

Best Practices

​

Local Environment

• Monitor permissions: Be aware of what tools can access
• Validate inputs: Sanitize tool parameters carefully
• Error handling: Implement robust error recovery
• Resource monitoring: Watch for resource usage

​

Docker Environment (if used)

• Container management: Properly clean up containers
• Volume security: Limit mounted directories
• Image maintenance: Keep base images updated
• Resource limits: Set appropriate container limits

​

General Recommendations

• Start with local: Use local environment for development
• Test thoroughly: Validate tool behavior in your chosen environment
• Monitor performance: Track execution times and resource usage
• Plan for scaling: Consider environment implications for production

​

Next Steps

• Learn about Agent Architecture to understand how environments integrate with agents
• Explore Session Management to see how environments affect session state
• Understand the Tool System to see how tools execute in different environments
• Check out Getting Started for practical environment setup examples