image

The image domain has 18 actions. On the meta surface they are all reached through arcane_image; on the individual surface each one is its own tool; on the dynamic surface run them with arcane_execute_action and the canonical ID.

Summary

Action	Title	Kind
`image.attestations`	Get image attestations	read
`image.build`	Build an image	write
`image.build_get`	Get image build	read
`image.build_list`	List image builds	read
`image.counts`	Get image usage counts	read
`image.delete`	Remove an image	destructive
`image.export`	Export image	read
`image.get`	Get image by ID	read
`image.history`	Get image history	read
`image.list`	List images	read
`image.patch`	Patch image	write
`image.patch_targets`	List image patch targets	read
`image.patches`	List image patches	read
`image.prune`	Prune unused images	destructive
`image.pull`	Pull an image	write
`image.search`	Search images	read
`image.tag`	Tag image	write
`image.upload`	Upload an image	write

Actions

`image.attestations`

Get image attestations

Get in-toto attestation statements attached to a Docker image

Kind: read
Required parameters: name
Meta tool: arcane_image with "action": "attestations"
Individual tool: arcane_image_attestations
Arcane route: GET /api/environments/{id}/images/{name}/attestations
Operation ID: get-image-attestations
Usage: Reads the in-toto attestations (SBOM, provenance) attached to an image in its registry, using saved registry credentials. name is a local image ID or reference (resolved through its repo digest, else its first tag, which is then looked up in the registry) or a registry reference not pulled locally. An image with neither digest nor tag yields an empty list, and a locally built tag fails unless the registry has an image of that name (whose attestations are then returned). platform (e.g. linux/amd64) selects one manifest of a multi-platform image, predicateType keeps one exact predicate URI, and statement=true adds the statement JSON bodies. Returns imageRef, subjectDigest and attestations with predicateType, digest and subject.
Related actions: image.get, vulnerability.image_scan

`image.build`

Build an image

Build a Docker image using BuildKit with streaming progress output

Kind: write
Required parameters: contextDir
Meta tool: arcane_image with "action": "build"
Individual tool: arcane_image_build
Arcane route: POST /api/environments/{id}/images/build
Operation ID: build-image
Usage: Builds with BuildKit (or the provider setting, local or depot) and waits for the result: status completed, activityId and the last output lines. A failed build is an error. contextDir is an absolute directory on the Arcane host (e.g. the buildsDirectory setting plus a build.browse path, filled with build.mkdir and build.upload) or a Git repository URL, cloned with saved git_repository credentials when they match. Set tags to name the image, and dockerfile or dockerfileInline, buildArgs, target, platforms, noCache, pull and push as needed. Every build is recorded: find its id with image.build_list for image.build_get.
Related actions: build.browse, build.upload, image.build_list, image.build_get, image.get

`image.build_get`

Get image build

Get a single image build history entry with output

Kind: read
Required parameters: buildId
Meta tool: arcane_image with "action": "build_get"
Individual tool: arcane_image_build_get
Arcane route: GET /api/environments/{id}/images/builds/{buildId}
Operation ID: get-image-build
Usage: Returns one build record (buildId from image.build_list) with its full settings, status, errorMessage, digest and the captured build output (outputTruncated is true beyond 2 MiB). A build of another environment gives 404.
Related actions: image.build_list, image.build

`image.build_list`

List image builds

Get a paginated list of image build history for an environment

Kind: read
Required parameters: none
Meta tool: arcane_image with "action": "build_list"
Individual tool: arcane_image_build_list
Arcane route: GET /api/environments/{id}/images/builds
Operation ID: list-image-builds
Usage: Pages through the environment’s build history, newest first (start, limit, default 20). Filter with status (running, success, failed) or provider, and search, which matches contextDir, dockerfile, username, provider and errorMessage but not tags. Items carry id, status, tags, contextDir, durationMs and errorMessage but no output. Pass the id to image.build_get for the log.
Related actions: image.build_get, image.build

`image.counts`

Get image usage counts

Get counts of images in use, unused, total, and total size

Kind: read
Required parameters: none
Meta tool: arcane_image with "action": "counts"
Individual tool: arcane_image_counts
Arcane route: GET /api/environments/{id}/images/counts
Operation ID: get-image-usage-counts
Usage: Returns imagesInuse, imagesUnused, totalImages and totalImageSize (bytes) for the environment, a cheap overview before image.prune. Use image.list for the images themselves.
Related actions: image.list, image.prune

`image.delete`

Remove an image

Remove a Docker image by ID

Kind: destructive — requires confirm: true
Required parameters: imageId
Meta tool: arcane_image with "action": "delete"
Individual tool: arcane_image_delete
Arcane route: DELETE /api/environments/{id}/images/{imageId}
Operation ID: remove-image
Usage: Removes one image (docker rmi). imageId takes an ID from image.list or a reference, and removing a reference of an image with other tags only untags it. Without force Docker refuses an image used by a container, or an image ID referenced by several tags. force=true overrides that, but an image a running container uses still cannot be removed. Also drops Arcane’s stored update records and, when imageId is the image ID (not a reference), its vulnerability scan. Use image.prune to remove unused images in bulk.
Related actions: image.list, image.prune, container.list

`image.export`

Export image

Download a Docker image as a tar archive

Kind: read
Required parameters: name
Meta tool: arcane_image with "action": "export"
Individual tool: arcane_image_export
Arcane route: GET /api/environments/{id}/images/{name}/export
Operation ID: export-image
Usage: Returns the image (name is an ID or reference) as a docker save tar archive, embedded as a base64 blob. Archives larger than ARCANE_MCP_MAX_DOWNLOAD_BYTES (4 MiB by default) are not returned. Load it back with image.upload.
Related actions: image.upload, image.get

`image.get`

Get image by ID

Get a Docker image by its ID

Kind: read
Required parameters: imageId
Meta tool: arcane_image with "action": "get"
Individual tool: arcane_image_get
Arcane route: GET /api/environments/{id}/images/{imageId}
Operation ID: get-image
Usage: Inspects one local image. imageId takes the ID from image.list or a reference such as busybox:1.37, and an unknown image gives 404. Returns the full sha256 id, repoTags, repoDigests (empty for images never pulled or pushed), config (env, cmd, entrypoint, labels, exposed ports), architecture, os, size and the pinnedReferences containers use.
Related actions: image.list, image.history, image.attestations, vulnerability.image_scan

`image.history`

Get image history

Get Docker image layer history

Kind: read
Required parameters: name
Meta tool: arcane_image with "action": "history"
Individual tool: arcane_image_history
Arcane route: GET /api/environments/{id}/images/{name}/history
Operation ID: get-image-history
Usage: Lists the layers of a local image (name is an ID or reference), newest first, each with id, created, createdBy (the Dockerfile instruction), size and tags. Use image.get for the image configuration.
Related actions: image.get, image.list

`image.list`

List images

Get a paginated list of Docker images

Kind: read
Required parameters: none
Meta tool: arcane_image with "action": "list"
Individual tool: arcane_image_list
Arcane route: GET /api/environments/{id}/images
Operation ID: list-images
Usage: Pages through the environment’s local images (start, limit, default 20). Search matches repo, tag, ID and pinned references, sort takes repo, tag, size, created, inUse or vulnerabilities. inUse=true/false filters by container use, and updates takes true/false or has_update, up_to_date, error, unknown and reads the stored results of image_update checks. Each item gives id (sha256), repoTags, size, inUse, usedBy and, when recorded, updateInfo and vulnerabilityScan.
Related actions: image.get, image.counts, image.delete, image_update.check_all, vulnerability.image_scan

`image.patch`

Patch image

Patches OS package vulnerabilities in the image using Copacetic, producing a new patched tag

Kind: write
Required parameters: imageId
Meta tool: arcane_image with "action": "patch"
Individual tool: arcane_image_patch
Arcane route: POST /api/environments/{id}/images/{imageId}/patch
Operation ID: patch-image
Usage: Patches the OS packages of a tagged, registry-pulled image (imageId from image.get or image.patch_targets) with Copacetic in the background and returns the patch record at status patching with patchedRef and activityId. Follow it with image.patches or activity.get. scanId set to the same image ID patches only the findings of its vulnerability.image_scan report (needs vulnerability management enabled). Without it every outdated package is updated. The output tag is patchedTag, or the source tag plus -suffix (suffix defaults to the imagePatchSuffix setting, else patched). Patches run one at a time, and timeoutSeconds defaults to the imagePatchTimeoutSec setting (600). Requires images:patch and a Docker daemon using the containerd image store.
Related actions: image.patch_targets, image.patches, vulnerability.image_scan, activity.get

`image.patch_targets`

List image patch targets

Retrieves scanned images with fixable vulnerability counts and their latest patch run

Kind: read
Required parameters: none
Meta tool: arcane_image with "action": "patch_targets"
Individual tool: arcane_image_patch_targets
Arcane route: GET /api/environments/{id}/images/patch-targets
Operation ID: list-image-patch-targets
Usage: Lists images whose completed vulnerability scan has fixable findings or that were patched before, with imageId, imageRef, fixableCount, totalCount, localOnly (never pulled, so not patchable) and lastPatch. Patch outputs themselves are left out. Needs vulnerability management enabled and vulnerabilities:read. Pages with start and limit (default 20), search matches the image name.
Related actions: image.patch, image.patches, vulnerability.image_scan

`image.patches`

List image patches

Retrieves the paginated image patch history for the environment

Kind: read
Required parameters: none
Meta tool: arcane_image with "action": "patches"
Individual tool: arcane_image_patches
Arcane route: GET /api/environments/{id}/images/patches
Operation ID: list-image-patches
Usage: Pages through the environment’s patch runs, newest first (start, limit), each with originalRef, patchedRef, mode (update-all or report), status (patching, completed, failed), packagesUpdated and error. Filter with status, and search matches originalRef and patchedRef. Use it to follow an image.patch run.
Related actions: image.patch, image.patch_targets

`image.prune`

Prune unused images

Remove unused Docker images

Kind: destructive — requires confirm: true
Required parameters: none
Meta tool: arcane_image with "action": "prune"
Individual tool: arcane_image_prune
Arcane route: POST /api/environments/{id}/images/prune
Operation ID: prune-images
Usage: Removes images no container uses and returns imagesDeleted and spaceReclaimed (bytes). Pass dangling=true to remove only untagged (dangling) images: without it, and without body.mode, Arcane removes every unused image, tagged ones included. body.mode (dangling, all, or olderThan with body.until such as 24h) overrides dangling, and olderThan removes every unused image, tagged ones included, created before until. Use system.prune_all to prune containers, networks, volumes and build cache too.
Related actions: image.counts, image.delete, system.prune_all

`image.pull`

Pull an image

Pull a Docker image from a registry with streaming progress output

Kind: write
Required parameters: imageName
Meta tool: arcane_image with "action": "pull"
Individual tool: arcane_image_pull
Arcane route: POST /api/environments/{id}/images/pull
Operation ID: pull-image
Usage: Pulls imageName (e.g. nginx or ghcr.io/org/app) at tag (Docker uses latest when no tag is given) and waits for the pull to finish. The result has status completed, activityId and the last progress lines, and a failed pull is an error. Credentials of registries saved with registry.create are used automatically for a matching host, but credentials (or auth), each {url, username, token, enabled: true}, override them for this pull, and a rejected login is retried anonymously.
Related actions: image.search, image.get, registry.list, activity.get

`image.search`

Search images

Search Docker Hub images

Kind: read
Required parameters: none
Meta tool: arcane_image with "action": "search"
Individual tool: arcane_image_search
Arcane route: GET /api/environments/{id}/images/search
Operation ID: search-images
Usage: Searches Docker Hub through the Docker daemon (docker search) by term, which is required. Results give name, description, starCount and official. Pass a name to image.pull. It does not list tags (use registry.repositories and registry.tags to browse a saved registry).
Related actions: image.pull, registry.repositories, registry.tags

`image.tag`

Tag image

Add a repository tag to an image

Kind: write
Required parameters: name, repository
Meta tool: arcane_image with "action": "tag"
Individual tool: arcane_image_tag
Arcane route: POST /api/environments/{id}/images/{name}/tag
Operation ID: tag-image
Usage: Adds a tag to an existing local image (docker tag): name is the source image ID or reference, repository the target name (e.g. registry.example.com/team/app) and tag the target tag (Docker uses latest when omitted). The source keeps its tags. Remove a tag with image.delete on the reference.
Related actions: image.get, image.list, image.delete

`image.upload`

Upload an image

Load a Docker image tar archive from a complete chunked upload session. multipart/form-data bodies are still accepted for backward compatibility. That form is deprecated and will be removed in a future release.

Kind: write
Required parameters: uploadId
Meta tool: arcane_image with "action": "upload"
Individual tool: arcane_image_upload
Arcane route: POST /api/environments/{id}/images/upload
Operation ID: upload-image
Usage: Loads a docker save archive (.tar, .tar.gz, .tgz, .tar.xz) into the environment: create a session with upload.session_create (kind image), send it with upload.chunk_put until complete, then pass its id as uploadId. The session is used up. Archives above the maxImageUploadSize setting (500 MB by default) fail, and the result’s stream holds Docker’s load output naming the loaded images.
Related actions: upload.session_create, upload.chunk_put, image.export, image.get