---
title: "[run] grants"
url: https://una-lang.org/en/docs/configure/run/grants/
release: v0.4.0
edition: "0.1 and later"
source: https://github.com/una-lang/una/blob/v0.4.0/docs/guide/configure/run/grants.md
---

# [run] grants

## What it does

`grants` lists the host capabilities, the authority to use the console, files, the clock and the like, that `una run` gives the entry's `main`. Each is written as a grant spec, a short text such as `"console"` or `"files:./data:read"` that names one capability and how far it reaches. There is no ambient authority, no authority a program has just by running: a host capability that is not granted is not there, and `una check` reports a `main` that needs one.

Learn more: [The host's capabilities and grants](https://una-lang.org/en/learn/capabilities/the-hosts-capabilities-and-grants/).

`una.toml`

```toml
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"

[run]
entry = "shop"
grants = ["console"]
```

`src/shop.una`

```una
module shop

pub main() -> Unit
  uses @console: Console[print]
=
  @console.print("the shop is open")
```

## Forms

```text
[run]
grants = ["console", "clock", "env", "keys:<keyfile>", "files:<path>:read", "files:<path>:write", "files:<path>:read,write", ...]
```

The grant specs:

| Grant spec | Grants |
| --- | --- |
| `console` | `Console[print]` |
| `clock` | `Clock[now]` |
| `env` | `Env[get]` |
| `keys:<keyfile>` | `Keys[hmac]`, with the keys of the file |
| `files:<path>:read`, `files:<path>:write`, `files:<path>:read,write` | the `Files` operations of the mode, under the path |
| `http:<origin>`, `http:<origin>:<methods>` (edition `0.2`) | `Http` operations for the origin |
| `http:` with limit suffixes, such as `http:<origin>;10/second` (edition `0.4`; this spec form is for `--grant`, and `ita.una` writes limits as lines) | the same, at most at that rate (`spec/27 §9`) |
| `serve:<scheme>://<address>:<port>`, with `;<item>` suffixes (edition `0.4`; this spec form is for `--grant`, and `ita.una` writes a `serve` line with item lines) | accepting connections at that address, and `HttpServer` (`spec/31 §2`; see [Serving HTTP](https://una-lang.org/en/docs/guides/serving-http/)) |

`una run` also takes `--grant <spec>` flags; the grants of `una.toml` and of the flags apply together. The grants of edition `0.4` are given with `--grant`, or in the `run` section of `ita.una` (see [`ita.una`](https://una-lang.org/en/docs/configure/ita/manifest/)); in `ita.una`, limits and `serve` items are lines below their grant. In `una.toml`, a `serve:` spec is U7002 in every edition.

## Examples

A host operation of `main` that no grant allows is reported before the program runs. Here the grant reads files and `main` writes one:

`una.toml`

```toml
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"

[run]
entry = "shop"
grants = ["files:./data:read"]
```

`src/shop.una`

```una
-- fails with U3012
module shop

pub main() -> Unit
  uses @files: Files[read, write]
=
  @files.write("orders.txt", content: "order 42")
    if error use unit
```

## Edge cases

**Only grant specs**:

`una.toml`

```toml
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"

[run]
entry = "shop"
grants = ["network"]
```

`src/shop.una`

```una
-- fails with U7002
module shop

pub price(cents: Int) -> Int = cents
```

Further rules:

- **Files stay under the grant.** A `Files` path is resolved under the grant's path, and path resolution never escapes it. Races on a path and hard links are outside the model.
- **Relative paths** in `una.toml` grants resolve against the package root, and those of flags against the current directory.
- **Host capabilities.** See [host capabilities and grants](https://una-lang.org/en/docs/language/capabilities/host/).

## Diagnostics

- [U3012](https://una-lang.org/en/docs/errors/U3012/): a host operation of `main` that no grant allows.
- [U7002](https://una-lang.org/en/docs/errors/U7002/): a grant that is not a grant spec.

## Edition

The grant specs of v0.1 are in editions `0.1`, `0.2` and `0.3`. Edition `0.2` adds the `http:` grants, which edition `0.3` keeps. From edition `0.4`, a package lists its grants in `ita.una` instead of `una.toml`, an `http` grant may carry limits, and the `serve` grant lets a program accept connections.

## Normative source

- `spec/13 §7`: `[run]`; `spec/13 §5`: grant specs and `una run`.
- `spec/05 §7`: host capabilities; `spec/14 §3`: their operations; `spec/24 §2`: `Http` grants.
- `spec/07 §1`: what is outside the model.
