Skip to content

Introduction

Miracle provides an IPC mechanism for interacting with the compositor at runtime. This socket is largely in line with both i3 and sway's IPC implementation.

The IPC protocol uses a UNIX socket as the method of communication. The path to the socket is stored in the environment variable MIRACLESOCK and, for backwards compatibility with sway, SWAYSOCK, and, for backwards compatibility with i3, I3SOCK.

Format

The format for messages and replies is:

    <magic-string> <payload-length> <payload-type> <payload>

Where
    <magic-string> is i3-ipc, for compatibility with i3
    <payload-length> is a 32-bit integer in native byte order
    <payload-type> is a 32-bit integer in native byte order

For example, sending the exit command would look like the following hexdump:

00000000 | 69 33 2d 69 70 63 04 00 00 00 00 00 00 00 65 78 |i3-ipc........ex|
00000010 | 69 74                                           |it              |

The payload for replies will be a valid serialized JSON data structure.

Messages

Each message is associated with a "Message Type" that is given by the number in parentheses. This is the value that users will send from the client when they want to send the corresponding message.

For those familiar with sway, miracle will always lack support for particular messages such as:

  • GET_CONFIG
  • GET_BAR_CONFIG

The following are unimplemented, but may be implemented in the future:

  • GET_INPUTS
  • GET_SEATS

Events

Commands