This page refers to an older version of Spin. Go to the latest version.

Spin Application Manifest (Version 1) Reference

This page describes version 1 of the Spin manifest file, typically called spin.toml.

There are two versions of the manifest format. The manifest format described here (version 1) is used for Spin 1.x, and is supported for backward compatibility in Spin 2.x and above. New applications targeting Spin 2 should use the version 2 manifest format.

Format

The manifest is a TOML file, and follows standard TOML syntax. See the TOML documentation for information about the TOML syntax.

Manifest Fields

NameRequired?TypeValueExample
spin_manifest_versionRequiredStringThe version of the file format that the rest of the manifest follows. Currently, this value must be "1"."1"
nameRequiredStringThe name of the application. This may be any string of alphanumeric characters, hyphens and underscores."hello-world"
versionRequiredStringThe version of the application. The must be a string of the form major.minor.patch, where each element is a number."1.0.5"
descriptionOptionalStringA human-readable description of the application."The best app for all your world-greeting needs"
authorsOptionalArray of stringsThe authors of the applications. If present, this must ba an array, even if it has only one entry.["Jane Q Hacker (<dev@example.com>)"]
triggerRequiredTableThe trigger for the application - that is, the kind of event that the application responds to. The table must contain the type field, and may contain others depending on the value of type. See The trigger Table for details.{ type = "http", base = "/" }
variablesOptionalTableDynamic configuration variables which the user can set when they run the application. See The variables Table below.[variables]
message = { default = "hello" }
componentRequiredTable arrayA manifest must contain at least one component table. component is always an array, even if there is only one component, so always use double square brackets. See The component Tables below.[[component]]
id = "hello"

The trigger Table

The trigger table specifies the events that the application responds to. The type field is always required, but the other fields depend on the type. This section describes the built-in http and redis trigger types.

Because the trigger table usually contains only a few simple fields, you will usually see it written inline using brace notation, rather than written out using square-brackets table syntax. For example:

trigger = { type = "http", base = "/" }

The trigger Table for HTTP Applications

NameRequired?TypeValueExample
typeRequiredStringAlways "http" for HTTP applications."http"
baseRequiredStringThe base path of the application. All component routes are relative to this. It allows multiple applications to be mounted under the same host."/"

The trigger Table for Redis Applications

NameRequired?TypeValueExample
typeRequiredStringAlways "redis" for Redis applications."redis"
addressRequiredStringThe address of the Redis instance the components are using the message subscriptions. Use the redis: URL scheme."redis://localhost:6379"

The variables Table

The keys of variables table are user-defined. The value of each key is another table with the fields shown in the following table.

Because each variables value usually contains only a few simple fields, you will usually see the table entries written inline with the values written using brace notation, rather than fully written out using square-brackets table syntax for each variable. For example:

[variables]
vessel = { default = "teapot" }
token = { required = true, secret = true }
NameRequired?TypeValueExample
defaultOptionalStringThe value of the variable if no value is supplied at runtime. If specified, the value must be a string. If not specified, required must be true."teapot"
requiredOptionalBooleanWhether a value must be supplied at runtime. If not specified, required defaults to false, and default must be providedfalse
secretOptionalBooleanIf set, this variable should be treated as sensitive.false

The component Tables

component is a table array, meaning each component is introduced with double-bracket syntax. Subtables are written using single-bracket syntax or inline JSON syntax. For example:

[[component]]
id = "hello"
source = "hello.wasm"
[component.trigger]
route = "/hello"

Each table in the component array contains the following fields:

NameRequired?TypeValueExample
idRequiredStringAn identifier for this component, unique within the application. This may be any string of alphanumeric characters, hyphens and underscores."cart-api"
descriptionOptionalStringA human-readable description of the component."The shopping cart API"
sourceRequiredString or tableThe Wasm module which should handle the component. This must be built to work with the application trigger. It can be in one of the following formats:
String* The path to a Wasm file (relative to the manifest file)dist/cart.wasm
Table* The URL of a Wasm file downloadable over HTTP. This must be a table containing a url field for the Wasm file, and a digest field contains a SHA256 hex digest, used to check integrity.{ url = "https://example.com/example.wasm", digest = "sha256:6503...2375" }
filesOptionalArray of strings and/or tablesThe files to be made available to the Wasm module at runtime. This is an array, and each element of the array is either:[ "images/*.jpg", { source = "assets/images", destination = "/pictures" } ]
String* A file path or glob pattern, relative to the manifest file. The matching file or files will be available in the Wasm module at the same relative paths."images/*.jpg"
Table* A directory to be made available to the Wasm module at a specific path. This must be a table containing a source field for the directory relative to the manifest file, and a destination field containing the absolute path at which to make it available.{ source = "assets/images", destination = "/pictures" }
exclude_filesOptionalArray of stringsAny files or glob patterns that should not be available to the Wasm module at runtime, even though they match a files entry.[assets/images/test/**/*.*]
allowed_http_hostsOptionalArray of stringsThe host names or addresses to which the Wasm module is allowed to send HTTP requests. If the name includes a port, the Wasm module can send requests only to that port; otherwise, the Wasm module can send requests only to the default port for the scheme it uses. The special string insecure:allow-all permits the module to send HTTP requests to any host, but is intended for development use only; some deployment environments may decline to honour it.["example.com", "localhost:8081"]
allowed_outbound_hostsOptionalArray of stringsThe addresses to which the Wasm component is allowed to send network requests. This applies to the outbound HTTP, outbound Redis, MySQL and PostgreSQL APIs. (It does not apply to built-in storage services such as key-value and SQLite.) Each entry must contain both a scheme, a name (or IP address) and a port in scheme://name:port format. For known schemes, you may omit the port if it is the default for the scheme. Use * for wildcards. If this field is omitted, no outbound access is permitted, except that, for backward compatibility, a Spin 1 component may use Redis, MySQL or PostgreSQL to any host. If this field is present and empty, however, no outbound access if permitted, regardless of the component’s Spin version.["mysql://db.example.com", "*://example.com:4567", "http://127.0.0.1:*"]
key_value_storesOptionalArray of stringsAn array of key-value stores that the Wasm module is allowed to read or write. A store named default is provided by the Spin runtime, though modules must still be permitted to access it. In current versions of Spin, "default" is the only store allowed.["default"]
environmentOptionalTableEnvironment variables to be set for the Wasm module. This is a table. The table keys are user-defined; the values must be strings.{ DB_URL = "mysql://spin:spin@localhost/dev" }
triggerRequiredTableSpecifies how this component is triggered. This is a table, whose contents of are trigger-specific; see below.[component.trigger]
route = "/..."
buildOptionalTableThe command that spin build uses to build this component. See The component.build Table below.[component.build]
command = "npm run build"
configOptionalTableDynamic configuration values to be made available to this component. The table keys are user-defined; the values must be strings, and may use template notation as described under Dynamic Configuration.[component.config]
api_base_url = "https://{{ api_host }}/v1"

The component.trigger Table for HTTP Applications

NameRequired?TypeValueExample
routeRequiredStringThe route which this component handles. Requests to the route will cause the component to execute. This may be an exact route (/example), which matches on the given path, or a wildcard route indicated by the suffix /... (/example/...), which matches any route under this prefix. If two routes overlap, requests are directed to the matching route with the longest prefix - see the HTTP trigger documentation for details and examples."/api/cart/..."
executorOptionalTableHow Spin should invoke the component. If present, this is a table. The type key is required and may have the values "spin" or "wagi". If omitted. the default is { type = "spin"}. See the HTTP trigger documentation for details.{ type = "wagi" }
If type = "spin" there are no other keys defined. In this case, Spin calls the component using a standard Wasm component interface. Components built using Spin SDKs or Spin interface files use this convention.{ type = "spin" }
If type = "wagi", Spin calls the component’s “main” (_start) function using a CGI-like interface. Components built using languages or toolchains that do not support Wasm interfaces will need to be called in this way. In this case, the following additional keys may be set:

* argv (optional): The string representation of the argv list that should be passed into the handler. ${SCRIPT_NAME} will be replaced with the script name, and ${ARGS} will be replaced with the query parameters of the request, formatted as arguments. The default is to follow the CGI specification, and pass ${SCRIPT_NAME} ${ARGS}

* entrypoint (optional): The name of the function to call as the entry point to this handler. By default, it is _start (which in most languages translates to main in the source code).

See the HTTP trigger documentation for details.		{ type = "wagi" }

The component.trigger Table for Redis Applications

NameRequired?TypeValueExample
channelRequiredStringThe Redis channel which this component handles. Messages on this channel will cause the component to execute."purchases"

The component.build Table

NameRequired?TypeValueExample
commandRequiredStringThe command to execute on spin build."cargo build --target wasm32-wasi --release"
workdirOptionalStringThe directory in which to execute command, relative to the manifest file. The default is the directory containing the manifest file. An example of where this is needed is a multi-component application where each component is its own source tree in its own directory."my-project"
watchOptionalArray of stringsThe files or glob patterns which spin watch should monitor to determine if the component Wasm file needs to be rebuilt. These are relative to workdir, or to the directory containing the manifest file if workdir is not present.["src/**/*.rs", "Cargo.toml"]

Next Steps