> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coralos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# PotentialStringReference

> A string.  The string's value can optionally be a reference to a file, URL or constant

## Inline

An inline value for a `PotentialStringReference` can be specified as a [string literal](https://toml.io/en/v1.1.0#string):

```toml theme={null}
value = "my string value"
```

Or explicitly with a discriminated table.  Example using a discriminated [inline table](https://toml.io/en/v1.1.0#inline-table):

```toml theme={null}
value = { type = "string", value = "my string value" }
```

## File

File references may be used to define the value of a `PotentialStringReference`.  File references will be resolved by
the Coral server, relative to the `coral-agent.toml` file.  For example, given the following structure:

<Tree>
  <Tree.Folder name="my-agent" defaultOpen>
    <Tree.File name="coral-agent.toml" />

    <Tree.File name="README.MD" />
  </Tree.Folder>
</Tree>

The value of `README.MD` could be used as a value with this syntax:

```toml theme={null}
value = { type = "file", path = "README.MD" }
```

File references will read the file as a string with the UTF-8 encoding by default.  This can be configured by using
adding an `encoding` field to the reference:

### encoding

<Badge color="blue">optional</Badge>

<Note>
  This field is ignored if `base64 = true`
</Note>

```toml theme={null}
value.type = "file"
value.path = "README.MD"
value.encoding = "windows-1251"
```

A list of supported encoding names can be found [here](https://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html).

### base64

<Badge color="blue">optional</Badge>

A file reference can also be a Base64 encoded string, which can be useful if the referenced file contains binary data.

```toml theme={null}
value.type = "file"
value.path = "image.png"
value.base64 = true
```

The default value for `base64` is `false`.  Certain usages of the `PotentialStringReference` type may have a default
`base64` value of `true` however, such as with options that have a `type = "blob"` or `type = "list[blob]"`

## URL

URL references may be used to define the value of a `PotentialStringReference`.  URL references are equivalent to
file references in all ways except that a `url` is given instead of a `path`.

```toml theme={null}
value = { type = "url", url = "https://my-server.com/my-agent/1.0.0/README.MD" }
```

### encoding

<Badge color="blue">optional</Badge>
Operates identically to file references.  See [here](/reference/types/potential-string-reference#encoding-optional)

### base64

<Badge color="blue">optional</Badge>
Operates identically to file references.  See [here](/reference/types/potential-string-reference#base64-optional)

## Constant references

Constant references are a special type of string reference that provides a mechanism for using a Coral server-provided string
constant as a value.  These are especially useful in prototype runtimes.

Constant references can be accessed via name:

```toml theme={null}
value.type = "constant"
value.name = "PROTOTYPE_DEFAULT_SYSTEM_PROMPT"
```

The following constants are available:

`PROTOTYPE_DEFAULT_SYSTEM_PROMPT`

The default value for `runtimes.prototype.prompts.system.base`

`PROTOTYPE_DEFAULT_LOOP_INITIAL_BASE_PROMPT`

The default value for `runtimes.prototype.prompts.loop.initial.base`

`PROTOTYPE_DEFAULT_LOOP_FOLLOWUP_PROMPT`

The default value for `runtimes.prototype.prompts.loop.followup`

`CORAL_STATE_RESOURCE_URI`

The MCP URI for the Coral state resource

`CORAL_INSTRUCTION_RESOURCE_URI`

The MCP URI for the Coral instruction resource