Resources, connections and attachments
Manage resource data and explicitly authorized connection secrets.
Availability
Connection tools require the resource-access feature to be enabled for your installation. Use alshitask_tools for the selected organization and project to discover available tools and their exact schemas.
The project diagram
Project resources are the diagram’s resource nodes. Creating a resource through the canvas, REST or MCP makes it appear automatically. Existing positions, connections and linked notes are retained. Search the resource list to focus a resource; there is no separate add-to-diagram step.
Resource removal means Move to Trash with confirmation. Archive and Trash hide resources while preserving their layout and connections; Restore makes them visible again. Drawing shapes and containers remain separate objects.
Note cards and connections
Place an existing project note on the canvas or create a new note there. Cards reference the original note: editing the note updates the card. Removing a card removes its placement and attached canvas connections without deleting the note. Notes linked to resources or connections are not automatically placed.
Use alshitask_write_project_graph with graph version 3, the current diagram revision, a mutation ID and explicit confirmation. Preserve resource nodes and drawing metadata. The note_cards map associates each placed note UUID with itself as the drawing shape UUID. Connections reference resource or shape IDs, with note endpoints identified by this map. Older graph writers are rejected when note-card references would be lost; reread the graph and use the versioned operation.
Connection permissions
Organization owners/admins and project managers can authorize connections within projects they manage. Existing credentials gain no new permissions automatically. Choose connection metadata read, connection write and secret retrieval separately. Connection write also requires permission to change project content. Project managers must select the specific projects they manage. Secret retrieval permits an external client to receive private SSH keys, environment values and connection files.
Configure a connection
Use alshitask_connection_metadata to read the current revision without secret values. Call alshitask_change_connection with a mutation ID, that revision and only fields being changed. Omitted fields remain unchanged. Set an environment or connection-file map entry to null to remove it; use clear_ssh to remove SSH configuration. Connection-file values are standard base64, matching the existing bundle format.
Use alshitask_connection_secrets only when you need the stored secret values. Keep keys and secrets in the connection bundle, outside resource descriptions, ordinary attachments and logs. These tools configure connections; they do not execute SSH commands.
Attachments
Upload a project file using alshitask_start_upload, alshitask_upload_part and alshitask_complete_upload. Then attach it with alshitask_change_file_link, using target_kind: resource and the resource ID. Use alshitask_resource_attachments for link revisions and file metadata.
Replacement publishes a new file revision; existing links follow the current revision. Detach removes a link without deleting a shared file. Archive, trash and restore remain available; permanent purge is not exposed through MCP. Existing file formats and quotas apply.
Use the returned upload part size. The default remains 8,000,000 bytes; supported installations accept an explicit part size between 5,242,880 and 8,000,000 bytes. Object storage requires that minimum for non-final parts. For clients with smaller tool-message limits, use a client-side uploader with the binary upload route described by discovery and an authorized Tasks-audience token. The gateway API key itself is not accepted by source REST routes. Preserve the upload ID and exact bytes when resuming.
Groups, health and history
Use group-write and resource-group-move tools with the current diagram revision. Health configuration requires project management authority and retains existing target validation and plan limits. Health email preferences affect only the authenticated user and require an explicit request and confirmation. Resource history never includes connection secrets.
Conflicts and failures
Validation errors, authorization denials, missing sources, revision conflicts and rate limits are distinct from an upstream outage. Read current state after a revision conflict. Preserve mutation IDs and exact arguments following an uncertain write; never submit a fresh mutation merely because the first response was lost.