> ## Documentation Index > Fetch the complete documentation index at: https://docs.firedrill.run/llms.txt > Use this file to discover all available pages before exploring further. # Connect to a ready Tool environment > Requires drill.run and a ready reusable environment. Returns a secret-bearing, scoped lease for ordinary Tool use; it does not run an agent, wake compute or change Tool state. Supply the observed runtime version and generation. Preserve the exact request and idempotency key after an uncertain response. Expired, revoked or stale grants cannot be replayed as current access; deliberate renewal uses a new key. Never automatically resend an uncertain Tool action after renewal. Responses are private and non-cacheable. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/projects/{projectId}/environments/{environmentId}/connections openapi: 3.1.0 info: title: Firedrill Control API version: 1.0.0 description: >- The control plane for drills, drill runs, and the worlds they run in. Errors always carry the canonical envelope; unsafe operations require an Idempotency-Key; long work returns an operation resource. servers: - url: https://api.firedrill.run security: - controlCredential: [] paths: /v1/projects/{projectId}/environments/{environmentId}/connections: post: summary: Connect to a ready Tool environment description: >- Requires drill.run and a ready reusable environment. Returns a secret-bearing, scoped lease for ordinary Tool use; it does not run an agent, wake compute or change Tool state. Supply the observed runtime version and generation. Preserve the exact request and idempotency key after an uncertain response. Expired, revoked or stale grants cannot be replayed as current access; deliberate renewal uses a new key. Never automatically resend an uncertain Tool action after renewal. Responses are private and non-cacheable. operationId: environments.connect parameters: - name: projectId in: path required: true schema: type: string pattern: ^prj_[0-9a-z]{12,32}$ - name: environmentId in: path required: true schema: type: string pattern: ^env_[0-9a-z]{12,32}$ - name: Idempotency-Key in: header required: true schema: type: string minLength: 8 maxLength: 128 pattern: ^[A-Za-z0-9._:-]+$ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IssueEnvironmentConnectionRequest' responses: '200': description: Exact environment selection and scoped connection lease content: application/json: schema: $ref: '#/components/schemas/EnvironmentConnectionResponse' '400': description: Canonical error envelope content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Canonical error envelope content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: Canonical error envelope content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Canonical error envelope content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '409': description: Canonical error envelope content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Canonical error envelope content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' default: description: Canonical error envelope content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: IssueEnvironmentConnectionRequest: type: object properties: actorId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ actorInstanceId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ expectedRuntimeVersion: type: integer minimum: -9007199254740991 maximum: 9007199254740991 expectedLeaseGeneration: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 ttlMs: type: integer minimum: 0 exclusiveMinimum: true maximum: 3600000 required: - actorId - expectedRuntimeVersion - expectedLeaseGeneration additionalProperties: false EnvironmentConnectionResponse: type: object properties: schemaVersion: type: number enum: - 1 selection: type: object properties: projectId: type: string pattern: ^prj_[0-9a-z]{12,32}$ environmentId: type: string pattern: ^env_[0-9a-z]{12,32}$ sessionId: type: string pattern: ^ses_[0-9a-z]{12,32}$ buildHash: type: string pattern: ^sha256:[0-9a-f]{64}$ runtimeVersion: type: integer minimum: -9007199254740991 maximum: 9007199254740991 leaseGeneration: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 actorId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ actorInstanceId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ actorBindingId: type: string pattern: ^actor_[A-Za-z0-9][A-Za-z0-9_-]{5,95}$ required: - projectId - environmentId - sessionId - buildHash - runtimeVersion - leaseGeneration - actorId - actorBindingId additionalProperties: false access: type: object properties: schemaVersion: type: number enum: - 1 sessionId: type: string pattern: ^ses_[0-9a-z]{12,32}$ environmentId: type: string pattern: ^env_[0-9a-z]{12,32}$ buildHash: type: string pattern: ^sha256:[0-9a-f]{64}$ actorId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ actorInstanceId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ hostedRunId: type: string pattern: ^hrun_[0-9a-z]{12,32}$ interactionId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ interactionClaim: type: object properties: claimId: type: string pattern: ^iclaim_[0-9a-z]{12,32}$ generation: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 runRevision: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 required: - claimId - generation - runRevision additionalProperties: false callbackReceiverBindingId: type: string pattern: ^cbr_[0-9a-z]{12,32}$ worldHttpUrl: type: string format: uri worldWireHttpUrl: type: string format: uri worldWireAuthorizationHeader: type: string enum: - X-Firedrill-World-Authorization worldMcpUrl: type: string format: uri credential: type: string minLength: 32 expiresAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 capabilities: minItems: 1 type: array items: type: object properties: packageId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ instanceId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ operationId: type: string minLength: 1 maxLength: 160 pattern: >- ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*(?:\.[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*)*$ required: - packageId - operationId additionalProperties: false required: - schemaVersion - sessionId - environmentId - buildHash - actorId - worldHttpUrl - credential - expiresAtMs - capabilities additionalProperties: false replayed: type: boolean required: - schemaVersion - selection - access - replayed additionalProperties: false ErrorEnvelope: type: object properties: code: type: string pattern: ^(control|world)\.[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$ message: type: string minLength: 1 correlationId: type: string minLength: 1 retryable: type: boolean retryAfterMs: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 operationId: type: string source: type: string enum: - platform - simulated_provider issues: type: array items: type: object properties: path: type: string code: type: string message: type: string required: - path - code - message additionalProperties: false details: type: object propertyNames: type: string additionalProperties: {} evidence: type: object properties: sessionId: type: string runId: type: string journalSeq: type: integer minimum: 0 maximum: 9007199254740991 buildHash: type: string additionalProperties: false required: - code - message - correlationId - retryable - source additionalProperties: true securitySchemes: controlCredential: type: http scheme: bearer description: Opaque control credential ````